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The Lift Web Framework 



Chapter 1 



Introduction 



The Lift Web Framework provides web application developers tools to make writing security, in- 
teracting, scalable web applications easier than with any other web framework. After reading Part 
I of this book, you should understand Lift's core concepts and be able to write Lift applications. 
But with anything, practice is important. I have been writing Lift and Scala for 4 years, and even 
I learn new things about the language and the framework on a weekly basis. Please consider Lift 
an path and an exploration, rather than an end point. 

"Yo, David, stop yer yappin'. I'm coming from Rails I Spring I Struts I Django and I want to get 
started super fast with Lift." See From MVC ( 13 on page 111). 

Lift is built on top of the Scala programming language. Scala runs on the Java Virtual Machine. Lift 
applications are typically packaged as WAR files and run as a J/EE Servlets or Servlet Filters. This 
book will provide you with the core concepts you need to successfully write Lift web applications. 
The book assumes knowledge of Servlets and Servlet containers, the Scala Language (Chapters 1-6 
of Beginning Scala gives you a good grounding in the language), build tools, program editors, web 
development including HTML and JavaScript, etc. Further, this book will not explore persistence. 
Lift has additional modules for persisting to relational and non-relational data stores. Lift doesn't 
distinguish as to how an object is materialized into the address space... Lift can treat any object 
any old way you want. There are many resources (including Exploring Lift) that cover ways to 
persist data from a JVM. 

Lift is different from most web frameworks and it's likely that Lift's differences will present a 
challenge and a friction if you are familiar with the MVC school of web frameworks 1 . But Lift 
is different and Lift's differences give you more power to create interactive applications. Lift's 
differences lead to more concise web applications. Lift's differences result in more secure and 
scalable applications. Lift's differences let you be more productive and make maintaining appli- 
cations easier for the future you or whoever is writing your applications. Please relax and work to 
understand Lift's differences... and see how you can make best use of Lift's features to build your 
web applications. 

Lift creates abstractions that allow easier expression of business logic and then maps those ab- 
stractions to HTTP and HTML. This approach differs from traditional web frameworks which 
build abstractions on top of HTTP and HTML and require the developer to bridge between com- 
mon business logic patterns and the underlying protocol. The difference means that you spend 
more time thinking about your application and less time thinking about the plumbing. 



1 This includes Ruby on Rails, Struts, Java Server Faces, Django, TurboGears, etc. 



4 CHAPTER 1. INTRODUCTION 

I am a "concept learner." I learn concepts and then apply them over and over again as situations 
come up. This book focuses a lot on the concepts. If you're a concept learner and like my stream 
on conciousness style, this book will likely suit you well. On the other hand, it may not. 

Up to date versions of this book are available in PDF form at http: //simply . 
liftweb.net/Simply_Lift.pdf. The source code for this book is available at 

https://github.com/dpp/simply_lift. 

If you've got questions, feedback, or improvements to this document, please join the conversation 
on the Lift Google Group. 

I'm a "roll up your sleaves and get your hands dirty with code" kinda guy... so let's build a simple 
Chat application in Lift. This application will allow us to demonstrate some of Lift's core features 
as well as giving a "smack in the face" demonstration of how Lift is different. 



Chapter 2 

The ubiquitous Chat app 



Writing a multi-user chat application in Lift is super-simple and illustrates many of Lift's core 
concepts. 

The Source Code can be found at https://github.com/dpp/simply_lift/tree/master/chat. 

2.1 The View 

When writing a Lift app, it's often best to start off with the user interface... build what the user 
will see and then add behavior to the HTML page. So, let's look at the Lift template that will make 
up our chat application. 

Listing 2.1: index.html 

i <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 

2 "http: //www.w3 . org/TR/xhtmll /DTD /xhtml 1-transitional . dtd"> 

3 <html xmlns="http: //www.w3 . org/1 999/xhtml"> 

4 <head><title>Home</title></head> 

5 <body class=" lif t : content_id=main"> 

6 <div id="main" class=" lif t : surround?with=def ault ; at=content "> 

7 < ! -- the behavior of the div — > 

8 <div class=" lift : comet ?type=Chat "> 

9 Some chat messages 
io <ul> 

ii <li>A message</li> 

12 <li class="clearable">Another message</li> 

13 <li class="clearable">A third message</li> 

14 </ul> 

15 </div> 

16 

17 <div> 

is <form class="lif t : f orm . a jax"> 

19 <input class="lift :ChatIn" id="chat_in" /> 

20 <input type=" submit " value="Say Something"/> 

21 </form> 

22 </div> 

23 </div> 
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24 </body> 

25 </html> 



It's a valid HTML page, but there are some hinky looking class attributes. The first one is <body 
class = "lif t : content_id=main">. The class in this case says "the actual page content is 
contained by the element with id='main'." This allows you to have valid HTML pages for each of 
your templates, but dynamically add "chrome" around the content based on one or more chrome 
templates. 

Let's look at the <div id="main">. It's got a funky class as well: 

lift : surround?with=def ault; at=content. This class invokes a snippet which sur- 
rounds the <div> with the default template and inserts the <div> and its children at the element 
with id "content" in the default template. Or, it wraps the default chrome around the <div>. For 
more on snippets, see 7.1 on page 78. 

Next, we define how we associate dynamic behavior with the list of chat elements: <div 
class = "lift : comet ?type=Chat ">. The "comet" snippet looks for a class named Chat that 
extends CometActor and enables the mechanics of pushing content from the CometActor to the 
browser when the state of the CometActor changes. 



2.2 The Chat Comet component 



The Actor Model provides state in functional languages include Erlang. Lift has an Actor library 
and Lift Actors (see 7.14) provides a powerful state and concurrency model. This may all seem 
abstract, so let's look at the Chat class. 

Listing 2.2: Chat.scala 

package code 
package comet 

import net . liftweb ._ 
import http._ 
import util ._ 
import Helpers. _ 



9 

10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 



/ * * 

* The screen real estate on the browser will be represented 

* by this component. When the component changes on the server 

* the changes are automatically reflected in the browser. 
*/ 

class Chat extends CometActor with CometListener { 
private var msgs: Vector [ String] = Vector () // private state 

/ * * 

* When the component is instantiated, register as 

* a listener with the ChatServer 



*/ 

def registerWith 

/ * * 



ChatServer 
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24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 



The CometActor is an Actor, so it processes messages 
In this case, we're listening for Vector [ String] , 
and when we get one, update our private state 
and reRender () the component. reRender () will 
cause changes to be sent to the browser. 



*/ 

override def lowPriority = { 

case v: Vector [String] => msgs 
} 



reRender ( ) 



/ * * 



* Put the messages in the li elements and clear 

* any elements that have the clearable class. 
*/ 

def render = "li *" #> msgs & ClearClearable 



The Chat component has private state, registers with the ChatServer, handles incoming mes- 
sages and can render itself. Let's look at each of those pieces. 

The private state, like any private state in prototypical object oriented code, is the state that defines 
the object's behavior. 

registerWith is a method that defines what component to register the Chat component with. Reg- 
istration is a part of the Listener (or Observer) pattern. We'll look at the definition of the Chat- 
Server in a minute. 

The lowPriority method defines how to process incoming messages. In this case, we're Pat- 
tern Matching (see Section 7.15) the incoming message and if it's a Vector [String] , then we 
perform the action of setting our local state to the Vector and re-rendering the component. The 
re-rendering will force the changes out to any browser that is displaying the component. 

We define how to render the component by defining the CSS to match and the replacement (See 
Section 7.10). We match all the <li> tags of the template and for each message, create an <li> 
tag with the child nodes set to the message. Additionally, we clear all the elements that have the 

clearable in the class attribute. 

That's it for the Chat CometActor component. 



2.3 The ChatServer 



The ChatServer code is: 



Listing 2.3: ChatServer.scala 



package code 
package comet 

import net . liftweb ._ 
import http._ 
import actor. _ 

/ * * 
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9 * A singleton that provides chat features to all clients. 
10 * It ' s an Actor so it's thread-safe because only one 
n * message will be processed at once. 

12 */ 

13 object ChatServer extends LiftActor with ListenerManager { 

14 private var msgs = Vector ( "Welcome" ) // private state 

15 

16 /** 

17 * When we update the listeners, what message do we send? 
is * We send the msgs, which is an immutable data structure, 

19 * so it can be shared with lots of threads without any 

20 * danger or locking. 

21 */ 

22 def createUpdate = msgs 

23 

24 / * * 

25 * process messages that are sent to the Actor. In 

26 * this case, we're looking for Strings that are sent 

27 * to the ChatServer. We append them to our Vector of 
2s * messages, and then update all the listeners. 

29 */ 

30 override def lowPriority = { 

31 case s: String => msgs :+= s; updateListeners ( ) 

32 } 

33 } 

The ChatServer is defined as an object rather than a class. This makes it a singleton which 
can be referenced by the name ChatServer anywhere in the application. Scala's singletons differ 
from Java's static in that the singleton is an instance of an object and that instance can be passed 
around like any other instance. This is why we can return the ChatServer instance from the 
registerWith method in that Chat component. 

The ChatServer has private state, aVector[String] representing the list of chat messages. Note 
that Scala's type inferencer infers the type of msgs so you do not have to explicitly define it. 

The createUpdate method generates an update to send to listeners. This update is sent when a 
listener registers with the ChatServer or when the updateListeners ( ) method is invoked. 

Finally the lowPriority method defines the messages that this component can handle. If the 
ChatServer receives a String as a message, it appends the String to the Vector of messages 
and updates listeners. 

2.4 User Input 

Let's go back to the view and see how the behavior is defined for adding lines to the chat. 

<f orm class="lift : f orm. a jax"> defines an input form and the form, a j ax snippet turns a 
form into an Ajax (see Section 7.12) form that will be submitted back to the server without causing 
a full page load. 

Next, we define the input form element: <input class="lift : Chatln" id="chat_in"/>. 
It's a plain old input form, but we've told Lift to modify the <input>'s behavior by calling the 
Chatln snippet. 



2.5. CHAT IN 

2.5 Chat In 

The Chat In snippet (See Section 7.1) is defined as: 

Listing 2.4: Chatln.scala 



i package code 

2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import js._ 

7 import JsCmds._ 
s import JE._ 

9 

io import comet . ChatServer 
n 

12 /* * 

13 * A snippet transforms input to output... it transforms 

w * templates to dynamic content. Lift's templates can invoke 

15 * snippets and the snippets are resolved in many different 

16 * ways including "by convention" . The snippet package 

17 * has named snippets and those snippets can be classes 

18 * that are instantiated when invoked or they can be 

19 * objects, singletons. Singletons are useful if there's 

20 * no explicit state managed in the snippet. 

21 */ 

22 object Chatln { 

23 

24 / * * 

25 * The render method in this case returns a function 

26 * that transforms NodeSeq => NodeSeq. In this case, 

27 * the function transforms a form input element by attaching 
2s * behavior to the input. The behavior is to send a message 

29 * to the ChatServer and then returns JavaScript which 

30 * clears the input . 

31 */ 

32 def render = SHtml . onSubmit (s => { 

33 ChatServer ! s 

34 SetValById("chat_in", "") 

35 }) 

36 } 



The code is very simple. The snippet is defined as a method that associates a function with form 
element submission, onSubmit. When the element is submitted, be that normal form submission, 
Ajax, or whatever, the function is applied to the value of the form. In English, when the user 
submits the form, the function is called with the user's input. 

The function sends the input as a message to the ChatServer and returns JavaScript that sets the 
value of the input box to a blank string. 
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2.6 Running it 

Running the application is easy. Make sure you've got Java 1.6 or better installed on your machine. 
Change directories into the chat directory and type sbt update -jetty-run. The Simple 
Build Tool will download all necessary dependencies, compile the program and run it. 

You can point a couple of browsers to http : / / localhost : 8 8 and start chatting. 

Oh, and for fun, try entering <script>alert (' I ownz your browser' ) ;<script> and 
see what happens. You'll note it's what you want to happen. 



2.7 What you don't see 

Excluding imports and comments, there are about 20 lines of Scala code to implement a multi- 
threaded, multi-user chat application. That's not a lot. 

The first thing that's missing is synchronization or other explicit forms of thread locking. The 
application takes advantage of Actors and immutable data structures, thus the developer can focus 
on the business logic rather than the threading and locking primatives. 

The next thing that's missing is routing and controllers and other stuff that you might have to do 
to wire up Ajax calls and polling for server-side changes (long or otherwise). In our application, 
we associated behavior with display and Lift took care of the rest (see Section 7.17). 

We didn't do anything to explicitly to avoid cross-site scripting in our application. Because Lift 
takes advantage of Scala's strong typing and type safety (see Section 7.16), Lift knows the differ- 
ence between a String that must be HTML encoded and an HTML element that's already properly 
encoded. By default, Lift applications are resistant to many of the OWASP top 10 security vulner- 
abilities (see Section 7.18). 

This example shows many of Lift's strengths. Let's expand the application and see how Lift's 
strengths continue to support the development of the application. 



Chapter 3 

Snippets and SiteMap 



Lift services HTTP request in three ways: generating HTML pages, low level HTTP responses 
(e.g., REST), and responding to Ajax/Comet requests. Lift treats each type of request differently 
to make the semantics for responding to each type of request most natural. Put another way, it's 
different to build a complex HTML page with lots of different components than to send back some 
JSON data that corresponds to a database record. 

In this chapter, we're going to explore how Lift does dynamic HTML page generation based on 
the incoming HTTP request and URL including putting "chrome" around the HTML page (menus, 
etc.), placing dynamic content on each page, and site navigation including access control. 

The code for this chapter can be found in the sample s/snippet_and_s it emap directory of the 
Simply Lift distribution. 

3.1 Starting at the beginning: Boot . scala 

When your Lift application first starts up, it executes the code in Boot.scala: 

Listing 3.1: Boot.scala 

i package bootstrap . liftweb 

2 

3 import net . liftweb ._ 

4 import util._ 

5 import Helpers. _ 

6 

7 import common. _ 

s import http._ 

9 import sitemap. _ 

10 import Loc._ 
n 

12 import code . snippet ._ 

13 

14 /* * 

15 * A class that's instantiated early and run. It allows the application 

16 * to modify lift's environment 

17 */ 

11 
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is class Boot { 

19 / * * 

20 * Calculate if the page should be displayed. 

21 * In this case, it will be visible every other minute 

22 */ 

23 def displaySometimes_? : Boolean = 

24 (millis / 1000L / 60L) % 2 == 

25 

26 def boot { 

27 // where to search snippet 

2s LiftRules . addToPackages ( "code" ) 

29 

30 // Build SiteMap 

31 def sitemap () : SiteMap = SiteMap ( 

32 Menu . i ( "Home" ) / "index", // the simple way to declare a menu 

33 

34 Menu . i ( "Sometimes" ) / "sometimes" >> If (displaySometimes_? _, 

35 S ? "Can't view now"), 

36 

37 // A menu with submenus 

38 Menu . i ( "Info" ) / "info" submenus ( 

39 Menu. i ( "About" ) / "about" >> Hidden >> LocGroup ( "bottom" ) , 

40 Menu. i ("Contact") / "contact", 

4i Menu. i ( "Feedback" ) / "feedback" >> LocGroup ( "bottom" ) 
« ) , 

43 

44 

45 Menu. i ("Sitemap") / "sitemap" >> Hidden >> LocGroup ( "bottom" ) , 

46 

47 Menu . i ( "Dynamic" ) / "dynamic", // a page with dynamic content 

48 

49 Par am. menu, 

50 

51 Menu . param [Which] ("Recurse", "Recurse", 

52 {case "one" => Full (First () ) 

53 case "two" => Full (Second () ) 

54 case "both" => Full (Both ()) 

55 case _ => Empty}, 

56 w => w.toString) / "recurse", 

57 

58 // more complex because this menu allows anything in the 

59 // /static path to be visible 

60 Menu, i ("Static") / "static" / **) 

61 

62 // set the sitemap. Note if you don't want access control for 

63 // each page, just comment this line out. 

64 LiftRules . setSiteMapFunc (( ) => sitemap ()) 

65 

66 //Show the spinny image when an Ajax call starts 

67 LiftRules . a jaxStart = 

68 Full(() => LiftRules . jsArtif acts . show ( "a jax-loader" ). cmd) 

69 

70 // Make the spinny image go away when it ends 
7i LiftRules . a jaxEnd = 
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72 Full(() => Lif tRules . jsArtif acts . hide ( "a jax-loader " ) . cmd) 

73 

74 // Force the request to be UTF-8 

75 Li ft Rules. early. append (_. setCharacterEncoding ( "UTF-8 " ) ) 

76 

77 // Use HTML5 for rendering 

7s LiftRules . htmlProperties . default . set ( (r : Req) => 

79 new Html5Properties (r . userAgent ) ) 

so } 



Rather than keeping configuration parameters in XML files, Lift keeps configuration parameters 
in code in Boot. Boot is executed once when the servlet container loads the Lift application. You 
can change many of Lift's execution rules in the LiftRules singleton during boot, but after boot, 
these parameters are frozen. 

3.1.1 LiftRules rules 

Most of the configuration parameters that define how Lift will convert an HTTP request into a 
response are contained in the LiftRules singleton. Some of the parameters for LiftRules are 
used commonly and some are very infrequently changed from their default. LiftRules can be 
changed during boot, but not at other times. So, set all your configuration in boot (or in methods 
that are called from boot). 

3.1.2 Properties and Run modes 

While many properties for your running application can be defined in Boot. seal a, there are 
some properties that are best defined in a text file. Lift supports multiple properties files per 
project. The properties files are loaded based on the user, machine and run mode. 

If you want to provide a configuration file for a subset of your application or for a specific envi- 
ronment, Lift expects configuration files to be named in a manner relating to the context in which 
they are being used. The standard name format is: 

modeName . userName . hostName . props 

examples: 

dpp . yak . props 
test . dpp . yak . props 
production . moose . props 
staging . dpp . props 
test. default. props 
default .props 

with hostName and userName being optional, and modeName being one of "test", "staging", "pro- 
duction", "pilot", "profile", or blank (for development mode). The standard Lift properties file 
extension is "props". 

Place properties files in the sre/main/resources/props directory in your project and they 
will be packaged up as part of the build process. 
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When you're developing your Lift application, the run mode (see 

net . liftweb .util .Props .mode) will be Development. When you deploy your appli- 
cation, pass -Drun . mode=production to your web container. In production mode, Lift 
aggressively caches templates, snippet classes, etc. 



3.1.3 By convention 

Lift, like Rails, will look for items in certain locations by convention. For example, Lift will look 
for classes that implement snippets in the xxx . snippet package where the xxx part is the main 
package for your application. You define one or more packages for Lift to look in with: 

i // where to search snippet 

2 LiftRules .addToPackages ("code") 

Here, we've added the code package to the list of packages that Lift will search through. You can 
also do LiftRules . addToPackages ( "com. f ruitbat .mydivision .myapplication" ) . 



3.1.4 Misc Rules 

We'll skip the sitemap definition until the next section. This rule defines how to show a spinning 
icon during Ajax calls (Lift will automatically show the spinning icon if this function is enabled): 

i //Show the spinny image when an Ajax call starts 

2 LiftRules . a jaxStart = 

3 Full(() => LiftRules . jsArtif acts . show ( "a jax-loader" ). cmd) 

And this rule sets the default character encoding to UTF-8 rather than the default platform encod- 
ing: 

i // Force the reguest to be UTF-8 

2 Li ft Rules. early. append (_. set Character Encoding ( "UTF-8 " ) ) 

Okay... you get the idea... there are plenty of parameters to tune during boot. 



3.1.5 Html5 

Prior to Lift 2.2, Lift treated all templates as XHTML and emitted XHTML to the browser. When 
the Lift project started in early 2007, this seemed like a Really Good Idea™. Turns out the world has 
not adopted XHTML and some JavaScript libraries, e.g. Google Maps, doesn't work on XHTML 
pages. Lift 2.2 introduced optional Html5 support both in the parser (so it could read Html5 
templates rather than requiring well formed XML in templates) and emits Html5 to the browser. 
Lift still processes pages as Scala NodeSeq elements, so no changes are required to the application. 

In order to keep Lift 2.2 apps backward compatible with Lift's XHTML support, by default the 
XHTML parser/serializer are used. However, it's recommended to use the Html5 support which 
can be turned on in boot with: 
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1 // Use HTML5 for rendering 

2 LiftRules . htmlProperties . default . set ( (r : Req) => 

3 new Html5Properties (r . userAgent ) ) 



3.2 SiteMap 

Lift has an optional feature called SiteMap. You don't have to use it. But if you do set a sitemap 
in boot, then Lift will use the sitemap as a white list of HTML pages for your site (note that REST 
URLs do not need to be listed in the sitemap). SiteMap defines navigation and access control, 
allows you to create hierarchical menus, grouped menu items, display the entire sitemap, a relative 
sitemap, as well breadcrumbs. This section will discuss some of SiteMap's capabilities. 

3.2.1 Defining the SiteMap 

The SiteMap must be defined in boot and is only defined once 1 . Typcially, you will define a 
function that returns a SiteMap instance: 

i // Build SiteMap 

2 def sitemap (): SiteMap = ... 

And then define the SiteMap in LiftRules: 

i // set the sitemap. Note if you don't want access control for 

2 // each page, just comment this line out. 

3 LiftRules . setSiteMapFunc (( ) => sitemap ()) 

In development mode, the function will be called on each page load to rebuilt the SiteMap. In all 
other Lift run modes, the sitemap will be built once during boot. 

A SiteMap is a collection of Menu instances. Each Menu has one Loc [_] and a set of Menu 
instances as submenus (zero or more). Each Menu instance has a unique name. 

If an HTML page is not defined in the sitemap, Lift will not serve it. SiteMap is a white list of 
pages to serve. Further, the Loc [_] has parameters that can include multiple access control rules. 



3.2.2 Simplest SiteMap 

The simplest sitemap defines a single page: 

def sitemap (): SiteMap = SiteMap (Menu. i ( "Home" ) / "index"; 



In development mode, the sitemap can be changed dynamically to support changes to site content without having 
to re-start your application each time navigation changes. This is a development-time feature only. There are significant 
performance penalties associated with rebuilding the sitemap on each page load including forcing the serialization 
of serving pages. There are plenty of features in SiteMap that allow you to enable /disable menu items and have 
dynamically generated submenus. Don't rely on Lift's development-mode menu reloading for your application design. 
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This is a SiteMap with a single menu item. The Menu has the name "Home" and will be displayed 
as the localized (see 8.1 on page 92) string "Home". The Menu.i method generates a Menu with a 
Loc [Unit] . 

3.2.3 Menu and Loc [_] 

You may be wondering why a Menu and a Loc [_] (short for location, pronouned "Loke") are 
separate and why the Loc takes a type parameter. 

A Menu contains a location and many submenus. The original thought was that you could have a 
single Loc [_] that might be placed in different places in the menu hierarchy. So, historically, they 
are separated, but there's a one to one relation between them. 

The Loc [_] takes a type parameter which defines a current value type for the Loc. For example, 
if the Loc refers to a page that will display a wiki page, then the type parameter of the Loc would 

be WikiPage: Loc [WikiPage] . 

Each Loc can have many parameters (know as LocParam, "loke param") that define behavior for 
the Loc [_] . These parameters include access control testing, template definition, title, group, etc. 

3.2.4 Access Control 

You can control access to the URL/page represented by the Loc with the I f ( ) LocParam: 

i / * * 

2 * Calculate if the page should be displayed. 

3 * In this case, it will be visible every other minute 

4 */ 

5 def displaySometimes_? : Boolean = 

6 (millis / 1000L / 60L) % 2 == 

7 

8 Menu . i ( "Sometimes" ) / "sometimes" >> If (displaySometimes_? _, 

9 S ? "Can't view now") 

We define a method that returns true if access is allowed. Adding the If () LocParam will 
restrict access to the page unless the function returns true. Menu items will not be visible for 
pages that do not pass the access control rules and even if the user types the URL into the browser, 
the page will not be displayed (by default, the user will be redirected by to the home page and an 
error will be displayed.) 

3.2.5 Hidden and Group 

Menu items can be hidden from the default menu hierarchy even if the page is accessible. The 
Hidden LocParam says "hide from default menu." 

i Menu . i ("About") / "about" >> Hidden >> LocGroup ( "bottom" ) 

Menu items can also be grouped together in a named group and then displayed: 
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1 <span class = "lif t : Menu . group?group=bottom"x/span> 



Which results in: 



i <a href="/about">About</a> <a href="/feedback">Feedback</a> <a href="/sitemap">Sitemap</a: 



3.2.6 Submenus 

You can nest menus: 



i // A menu with submenus 

2 Menu . i ( "Info" ) / "info" submenus ( 

3 Menu. i ( "About" ) / "about" >> Hidden >> LocGroup ( "bottom" ) , 

4 Menu. i ("Contact") / "contact", 

5 Menu. i ( "Feedback" ) / "feedback" >> LocGroup ( "bottom" ) ) 

The About, Contact and Feedback pages are nested under the Info page. 

3.2.7 Parameters 

You can parse the incoming URL and extract parameters from it into type-safe variables: 

i // capture the page parameter information 
2 case class Paramlnf o (theParam: String) 

3 

4 // Create a menu for /param/somedata 

5 val menu = Menu . param [Paramlnf o] ("Param", "Param", 

6 s => Full (Paramlnfo (s) ) , 

7 pi => pi. theParam) / "param" 

The above code creates a menu called "Param". The menu is for the url /param/xxx where xxx 
can match anything. 

When the URL /param/dogfood or /param/ fruitbat is presented, it matches the Loc and 
the function (s => Full (Paramlnfo (s) ) ) is invoked. If it returns a Full Box, the value is 
placed in the Loc's currentValue. 

It's possible to hand-write Loc implementation that will match many URL parameters. 

For information on accessing the captured parameters (in this case the Paramlnfo), see 3.4.5 on 
page 23. 

3.2.8 Wildcards 

You can create menus that match all the contents of a given path. In this case, all the html files in 
/static/ will be served. That includes /static/index, /static/f ruitbat, and /stat- 
ic/moose/frog/wombat/meow. 
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1 II more complex because this menu allows anything in the 

2 // /static path to be visible 

3 Menu. i ("Static") / "static" / ** 

Note that Lift will not serve any files or directories that start with . (period) or _ (underscore) or 
end with -hidden. 



3.2.9 Summary 

We've demonstrated how to create a SiteMap with many different kinds of menu items. Next, 
let's look at the views. 



3.3 View First 

Once the access control is granted by SiteMap, Lift loads the view related to the URL. There are 
many mechanisms that Lift uses to resolve a path to a view, but the simplest is a one to one 
mapping between the URL path and the files in /src/main/webapp. If the URL is /index, then 
Lift will look for the localized (see 8.1 on page 92) version of /src/main/webapp/ index . html. 
Once Lift loads the template, Lift processes it to transform it into the dynamic content you want 
to return in response to the URL input. 

3.3.1 Page source 

Let's look at the page source: 

Listing 3.2: index.html 

i <!DOCTYPE html> 

2 <html> 

3 <head> 

4 <meta content="text/html; charset=UTF-8 " http-equiv="content-type" /> 

5 <title>Home</title> 

6 </head> 

7 <body class=" lif t : content_id=main"> 

8 <div id="main" class="lif t : surround?with=def ault&at=content "> 

9 <div>Hello World. Welcome to your Lift application . </div> 

10 <div>Check out a page with <a href="/param/f oo">query parameters</a> . </div> 
n 

12 <span class=" lift : embed?what=_embedme"> 

13 replaced with embedded content 
H </span> 

15 

i6 <div> 

17 BADTAB<ul> 

is BADTAB <li>Recursive : <a href =" /recurse/one">First snippet</a></li> 

19 BADTAB <li>Recursive : <a href =" /recurse/two">Second snippet</a></li> 

20 BADTAB <li>Recursive : <a href =" /recurse/both">Both snippets</a></li> 

21 BADTAB</ul> 



22 
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</div> 

23 </div> 

24 </body> 

25 </html> 

We can open the page in our browser: 

Hello World. Welcome to your Lift application. 
Check out a page with query parameters , 
replaced with embedded content 



3.3.2 Dynamic content 

The template is a legal HTML page. But there are marker in the page to tell Lift how to interpret 
the HTML. 

If the <body> tag contains a class attribute lift : content_id=xxxx, then Lift will find the 
element with the matching id and use that as the starting point for rendering the page. This 
allows your designers to edit and maintain the pages in the same hierarchy that you use for your 
application. 

3.3.3 Surround and page chrome 

The template processing starts with: 

i <div id="main" class="lif t : surround?with=def ault&at=content "> 

The class attribute lift : surround?with=def ault; at = content instructs Lift to surround 
the current Element with the template named default.html (typically located in the /templates- 
hidden/ directory), and place the current page's content at the element with the "content" id. 

This pattern allows us to wrap a common chrome around every page on our site. You can also 
specify different template to use for surrounding. Further, the template itself can choose different 
templates to use for surrounding. 

3.3.4 Embed 

In addition to surrounding the page with chrome, you can also embed another file. For example, 
you could have a shopping cart component that is embedded in certain pages. We embed with: 

i <span class="lift : embed?what=_embedme"> 

2 replaced with embedded content 

3 </span> 

Once again, the command is signalled with a class attribute that starts with lif t : . In this case, 
we embed a template from the file _embedme . html. 
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3.3.5 Results 

The resulting dynamically generated page looks like: 

app 



Home 
Sometimes 






Dynamic 



?.-■: 



Hello World. Welcome to your Lift application. 

Check out a page with query parameters . 

Howdy. I'm a bit of embedded content. I was embedded from Home. 



Here are some more menu items: 
About Feedback Sitemap 



Lift is Copyright 2007-20W Worldwide Conferencing, LLC. Distributed under an Apache 2.0 Liccns. 



3.4 Snippets and Dynamic content 

Lift templates contain no executable code. They are pure, raw, valid HTML. 

Lift uses snippets to transform sections of the HTML page from static to dynamic. The key word 
is transform. 

Lift's snippets are Scala functions: NodeSeq => NodeSeq. A NodeSeq is a collection of XML 
nodes. An snippet can only transform input NodeSeq to output NodeSeq. Well, not exactly... 
a snippet may also have side effects including setting cookies, doing database transactions, etc. 
But the core transformation concept is important. First, it isolates snippet functionality to discrete 
parts of the page. This means that each snippet, each NodeSeq => NodeSeq, is a component. 
Second, it means that pages are recursively built, but remain as valid HTML at all times. This 
means that the developer has to work hard to introduce a cross site scripting vulnerability. Third, 
the designers don't have to worry about learning to program anything in order to design HTML 
pages because the program execution is abstracted away from the HTML rather than embedded 
in the HTML. 

3.4.1 Snippets in markup 

In order to indicate that content is dynamic, the markup contains a snippet invocation. That typ- 
ically takes the form class="someclass someothercss lift :mysnippet ". If a class at- 
tribute contains 1 i f t : xxx, the xxx will be resolved to a snippet. The snippet may take attributes. 
Attributes are encoded like URL parameters... offset by a ? (question mark), then name=value, 
separted by ? (question mark), ; (semicolon) or & (ampersand), name and value are URL en- 
coded. 

You may also invoke snippets with XML tags: 

i <lift :my_snippet cat="foo"> 

2 <div>xxxx</div> 

3 </lift :my_snippet> 
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Note that the Html5 parser will force all tags to lower case so <lift :MySnipet> will become 
<lift :mysnippet>. 

Lift 2.3 will also allow snippet invocation in the form <div 
1= "my snippet ?param=value">xxx</div>. 

The latter two mechanisms for invoking snippets will not result in valid Html5 templates. 

3.4.2 Snippet resolution 

Lift has a very complex set of rules to resolve from snippet name to NodeSeq => NodeSeq (see 23.1 
on page 141). For now, the simplest mechanism is to have a class or object in the snippet 
package that matches the snippet name. 

So lift : HelloWorld will look for the code . snippet . HelloWorld class and invoke the ren- 
der method. 

lift : CatFood. f ruitbat will look for the code . snippet . CatFood class and invoke the 
f ruitbat method. 



3.4.3 Dynamic Example 

Let's look at the dynamic . html page: 

Listing 3.3: dynamic.html 

i <!DOCTYPE html> 

2 <html> 

3 <head> 

4 <meta content="text/html; charset=UTF-8 " http-equiv="content-type" /> 

5 <title>Dynamic</title> 

6 </head> 

7 <body class=" lif t : content_id=main"> 

8 <div id="main" class="lif t : surround?with=def ault ; at=content "> 

9 This page has dynamic content. 

10 The current time is <span class=" lift : HelloWorld">now</span> . 
n </div> 

12 </body> 

13 </html> 

This template invokes the HelloWorld snippet defined in HelloWorld. scala: 

Listing 3.4: Hello World, scala 

i package code 
2 package snippet 

3 

4 import lib._ 

5 

6 import net . liftweb ._ 

7 import util . Helpers ._ 

8 import common. _ 

9 import Java . util . Date 
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10 

ii class HelloWorld { 

12 lazy val date: Box [Date] = DependencyFactory . in ject [Date] // inject the date 

13 

14 def render = "* *" #> date .map (_. toString) 

15 } 



And the dynamic content becomes: 



i <span>Thu Dec 30 16:31:13 PST 2010</span> 



The HelloWorld snippet code is simple. 



i lazy val date: Box[Date] = DependencyFactory . in ject [Date] 

Uses dependency injection (see 8.2 on page 94) to get a Date instance. 
Then: 

i def render = "* *" #> date .map (_. toString) 

Creates a CSS Selector Transform (see 7.10 on page 85) that inserts the String value of the injected 
Date into the markup, in this case the <span> that invoked the snippet. 

3.4.4 Embedded Example 

We've seen how we can embed a template using: <div class="lift : embed?what=_em- 
bedme">xxx</div>. 

Let's look at the _embedme . html template: 

i <!DOCTYPE html> 

2 <html> 

3 <head> 

4 <meta content="text/html; charset=UTF-8 " http-equiv="content-type" /> 

5 <title>I'm embeded</title> 

6 </head> 

7 <body class=" lif t : content_id=main"> 

8 <div id="main"> 

9 Howdy. I'm a bit of embedded content. I was 

io embedded from <span class="lift : Embedded. f rom">???</span> . 
ii </div> 

12 </body> 

13 </html> 



And the invoked Embedded . seal a program: 

Listing 3.5: Embedded.scala 



i package code 
2 package snippet 

3 
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4 import lib._ 

5 

6 import net . liftweb ._ 

7 import http._ 

8 import util . Helpers ._ 

9 import common. _ 

10 import Java . util . Date 
n 

12 / * * 

13 * A snippet that lists the name of the current page 

14 */ 

15 object Embedded { 

i6 def from = "*" #> S . location .map (_. name) 

17 } 

The template invokes the from method on the Embedded snippet. In this case, the snippet is 
an object singleton because it does not take any constructor parameters and has no instance 
variabled. 

The from method: 

i def from = "*" #> S . location .map (_. name) 

Creates a CSS Selector Transform that replaces the contents with the name of the current loca- 
tion. 



3.4.5 Param Example 

Above, we saw how to create a Loc [Par am Info] to capture URL parameters. Let's look at the 
/param/xxx page and see how we can access the parameters: 

Listing 3.6: param.html 

i <!DOCTYPE html> 

2 <html> 

3 <head> 

4 <meta content="text/html; charset=UTF-8 " http-equiv="content-type" /> 

5 <title>Param</title> 

6 </head> 

7 <body class=" lif t : content_id=main"> 

8 <div id="main" class="lif t : surround?with=def ault ; at=content "> 

9 <div> 

10 Thanks for visiting this page. The parameter is 
n <span class="lift : ShowParam">???</span> . 
12 </div> 

13 

14 <div> 

15 Another way to get the param: <span class="lif t : Param">???</span> . 
i6 </div> 

17 

is </div> 
19 </body> 
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20 </html> 

And let's look at two different snippets that can access the Paramlnf o for the page: 

Listing 3.7: Param.scala 

i package code 
2 package snippet 

3 

4 import lib._ 

5 

6 import net . liftweb ._ 

7 import util . Helpers ._ 
s import common. _ 

9 import http._ 
10 import sitemap. _ 
n import Java . util . Date 

12 

13 // capture the page parameter information 
w case class Paramlnf o (theParam: String) 

15 

16 // a snippet that takes the page parameter information 

17 class ShowParam (pi : Paramlnf o) { 
is def render = "*" #> pi. theParam 

19 } 

20 

21 object Param { 

22 // Create a menu for /param/somedata 

23 val menu = Menu . param [Paramlnf o] ("Param", "Param", 

24 s => Full (Paramlnf o (s )) , 

25 pi => pi. theParam) / "param" 

26 lazy val loc = menu.toLoc 

27 

28 def render = "*" #> loc . currentValue .map (_. theParam) 

29 } 

Each snippet has a render method. However, the ShowParam class takes a constructor parameter 
which contains the Par am Info from the current Loc [_] . If the current Loc does not have the 
type parameter Paramlnf o, no instance of ShowParam would be created and the snippet could 
not be resolved. But we do have a Loc[ParamInfo], so Lift constructs a ShowParam with the Loc's 
currentValue and then the render method is invoked and it returns a CSS Selector Transform 
which is a NodeSeq => NodeSeq. 

The object Param's render method accesses the Loc [Paramlnf o] directly. The render 
method gets the Loc's currentValue and uses that to calculate the return value, the CSS Se- 
lector Transform. 

3.4.6 Recursive 

Lift's snippets are evaluated lazily. This means that the body of the snippet is not executed until 
the outer snippet is executed which allows you to return markup from a snippet that itself contains 
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a snippet or alternatively, choose part of the snippet body that itself contains a snippet invocation. 
For example, in this markup: 

Listing 3.8: recurse.html 

i <div id="main" class="lift : surround?with=def ault&at=content "> 

2 <div> 

3 This demonstrates Lift's recursive snippets 

4 </div> 

5 

6 <div class="lif t : Recurse"> 

7 <div id="first" class="lif t : FirstTemplate"> 

8 The first template. 

9 </div> 

10 

ii <div id="second" class="lift : SecondTemplate"> 

12 The second template. 

13 </div> 
w </div> 

15 

i6 <div> 

17 <ul> 

is <li>Recursive : <a href =" /recurse/one">First snippet</a></li> 

19 <li>Recursive : <a href =" /recurse/two">Second snippet</a></li> 

20 <li>Recursive : <a href =" /recurse/both">Both snippets</a></li> 

21 </ul> 

22 </div> 

23 </div> 

The Recur se snippet chooses one of both of the <div>'s, each of which invokes a snippet them- 
selves. Here's the Scala: 

Listing 3.9: Recurse.scala 

i package code 

2 package snippet 

3 

4 import lib._ 

5 

6 import net . liftweb ._ 

7 import util._ 

8 import Helpers. _ 

9 import http._ 

10 import scala . xml .NodeSeq 
n 

12 /* * 

13 * The choices 

14 */ 

15 sealed trait Which 

i6 final case class First () extends Which 

17 final case class Second () extends Which 

is final case class Both() extends Which 

19 

20 / * * 

2i * Choose one or both of the templates 
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22 */ 

23 class Recurse (which : Which) { 

24 // choose the template 

25 def render = which match { 

26 case First () => "#first AA " #> "*" // choose only the first template 

27 case Second () => "tsecond '"" s " #> "*" // choose only the second template 

28 case Both() => ClearClearable // it's a passthru 

29 } 

30 } 
31 

32 /* * 

33 * The first template snippet 

34 */ 

35 object FirstTemplate { 

36 // it's a passthru, but has the notice side effect 

37 def render (in: NodeSeq) = { 

38 S . notice ( "First Template Snippet executed") 

39 in 

40 } 

41 } 
42 

43 / * * 

44 * The second template snippet 

45 */ 

46 object SecondTemplate { 

47 // it's a passthru, but has the notice side effect 

48 def render (in: NodeSeq) = { 

49 S . notice ( "Second Template Snippet executed") 
so in 

51 } 

52 } 

Depending on the value of whi ch, one or both parts of the markup will be chosen. And each part 
of the markup itself invokes a snippet which displays a notice and passes the markup through. 

Using this technique, you can have a snippet that chooses one or many different snippets or re- 
turns a lif t : embed snippet, thus allowing for very dynamic markup generation. 

3.4.7 Summary 

We've seen some simple examples of Lift's snippet mechanism used to generate dynamic content. 
You can read more on snippets (see 7.1 on page 78). 

3.5 Wrap up 

In this chapter, we've seen how to define application behavior on Boot . scala. We've explored 
Lift's SiteMap which is used to generate navigation and enforce access control. We've seen how 
Lift's templating system works (well, there are actually a bunch of different ways to template in 
Lift, but we've explored to most common mechanism.) We've seen how snippets work. 

In the next chapter, we'll take a dive into Lift's form handling. 



Chapter 4 



Forms 



In this chapter, we'll see how Lift processes templates. We'll start with form processing the old 
fashioned way (where the designer names the inputs and the application maps those names to 
variables) through multi-page input forms and Ajax form support. 



4.1 Old Fashioned Dumb Forms 

Let's take a look at the HTML for a form: 

Listing 4.1: dumb.html 

i <div id="main" class="lift : surround?with=def ault&at=content "> 

2 <div> 

3 This is the simplest type of form processing... plain old 

4 mechanism of naming form elements and processing the form elements 

5 in a post-back. 

6 </div> 

7 

8 <div> 

9 <form action=" /dumb" method="post " class=" lift : DumbForm"> 
10 Name: <input name="name"xbr> 

n Age: <input name="age"xbr> 

12 <input type=" submit " value="Submit "> 

13 </form> 
w </div> 

15 </div> 

Okay... looks pretty normal... we define a form. The only thing we do is associate the behavior 
with the form with the class="lift :DumbForm" attribute on the <form> tag. The page is a 
post-back which means that the form is posted to the same URL that served the original content. 

Let's see the code to process the form: 

Listing 4.2: DumbForm.scala 

i package code 
2 package snippet 

27 
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3 

4 import net . liftweb ._ 

5 import http._ 

6 import scala . xml .NodeSeq 

7 

8 / * * 

9 * A snippet that grabs the query parameters 
10 * from the form POST and processes them 

n */ 

12 object DumbForm { 

13 def render (in: NodeSeq) : NodeSeq = { 

14 

15 // use a Scala f or-comprehension to evaluate each parameter 

16 for { 

17 r <- S. request if r.post_? // make sure it's a post 
is name <- S . param ( "name" ) // get the name field 

19 age <- S .param ( "age" ) // get the age field 

20 } { 

21 // if everything goes as expected, 

22 // display a notice and send the user 

23 // back to the home page 

24 S . notice ( "Name : "+name) 

25 S . notice ( "Age : "+age) 

26 S . redirectTo ( "/" ) 

27 } 
28 

29 // pass through the HTML if we don't get a post and 

30 // all the parameters 

31 in 

32 } 

33 } 



It's pretty simple. If the request is a post and the query parameters exist, then display notices with 
the name and age and redirect back the application's home page. 

There are plenty of reasons not to do things this way. 

First, if there's a naming mis-match between the HTML and the Scala code, you might miss a form 
field... and keeping the naming aligned is not always easy. 

Second, forms with predictable names lead to replay attacks. If an attacker can capture the form 
submits you've made and substitute new values for import fields, they can more easily hack your 
application. 

Third, keeping state around becomes very difficult with manual forms. You have to resort to 
hidden fields that contain primary keys or other information that can be tampered with. 

Lift provides you with much more powereful and secure mechanisms for dealing with HTML 
forms. 



4.2. ONSUBMIT 29 

4.2 OnSubmit 

Some of Lift's design reflects VisualBasic... associating user behavior with a user interface element. 
It's a simple, yet very powerful concept. Each form element is associated with a function on the 
server 1 . Further, because functions in Scala close over scope (capture the variables currently in 
scope), it's both easy and secure to keep state around without exposing that state to the web 
client. 

So, let's see how it works. First, the HTML: 

Listing 4.3: onsubmit.html 

i <div id="main" class=" lift : surround?with=def ault&at=content "> 

2 <div> 

3 Using Lift's SHtml . onSubmit , we've got better control 

4 over the form processing. 

5 </div> 

7 <div> 

8 <form class="lift : OnSubmit ?form=post "> 

9 Name: <input name="name"xbr> 

10 Age: <input name="age" value=" "><br> 

n <input type=" submit " value="Submit "> 

12 </form> 

13 </div> 

14 </div> 

The only different thing in this HTML is < form class="lift : OnSubmit ?f orm=post ">. The 
snippet, behavior, of the form is to invoke OnSubmit . render. The f orm=post attribute makes 
the form into a post-back. It sets the method and action attributes on the <f orm> tag: <f orm 

method="post " action^" /onsubmit ">. 



Let's look at the snippet: 



Listing 4.4: OnSubmit.scala 



i package code 

2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import util . Helpers ._ 

7 import scala . xml .NodeSeq 

8 

9 / * * 

io * A snippet that binds behavior, functions, 

n * to HTML elements 

12 */ 

13 object OnSubmit { 

14 def render = { 

15 // define some variables to put our values into 
i6 var name = " " 



1 Before you get all upset about statefulness and such, please read about Lift and State (see 20 on page 131). 
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17 var age = 

18 

19 // process the form 

20 def process ( ) { 

21 // if the age is < 13, display an error 

22 if (age < 13) S.error ("Too young!") 

23 e 1 s e { 

24 // otherwise give the user feedback and 

25 // redirect to the home page 

26 S . notice ( "Name : "tname) 

27 S . notice ( "Age : "+age) 
2s S . redirectTo ("/" ) 

29 } 

30 } 
31 

32 // associate each of the form elements 

33 // with a function. . . behavior to perform when the 

34 // for element is submitted 

35 "name=name" #> SHtml . onSubmit (name = _) & // set the name 

36 // set the age variable if we can convert to an Int 

37 "name=age" #> SHtml . onSubmit (s => aslnt(s) .foreach(age = _) ) & 

38 // when the form is submitted, process the variable 

39 "type=submit " #> SHtml . onSubmitUnit (process ) 

40 } 

41 } 

Like DumbForm . scala, the snippet is implemented as a singleton. The render method declares 
two variables: name and age. Let's skip the process () method and look at the was we're 
associating behavior with the form elements. 

"name=name" #> SHtml . onSubmit (name = _) takes the incoming HTML elements with 
the name attribute equal to "name" and, via the SHtml . onSubmit method, associating a function 
with the form element. The function takes a String parameter and sets the value of the name 
variable to the String. The resulting HTML is < input name="F10714412223674KM">. The 
new name attribute is a GUID (globally unique identifier) that associates the function (set the 
name to the input) with the form element. When the form is submitted, via normal HTTP post 
or via Ajax, the function will be executed with the value of the form element. On form submit, 
perform this function. 

Let's see about the age form field: "name=age" #> SHtml . onSubmit (s => 

aslnt(s) .foreach(age = _) ) . The function that's executed uses Helpers . aslnt to 
try to parse the String to an Int. If the parsing is successful, the age variable is set to the parsed 

Int. 

Finally, we associate a function with the submit button: "type=submit" #> 
SHtml . onSubmitUnit (process) . SHtml . onSubmitUnit method takes a function that 
takes no parameters (rather than a function that takes a single String as a parameter) and 
applies that function when the form is submitted. 

The process () method closes over the scope of the name and age variables and when that 
method is lifted to a function, it still closes over the variables... that means that when the function 
is applied, it refers to the same instances of the name and age variables as the other functions in 
this method. However, if we had 85 copies of the form open in 85 browsers, each would be closing 
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over different instances of the name and age variables. In this way, Lift allows your application 
to contain complex state without exposing that complex state to the browser. 

The problem with this form example is that if you type an incorrect age, the whole form is reset. 
Let's see how we can do better error handling. 



4.3 Stateful Snippets 

In order for us to give the user a better experience, we need to capture the state of the name and age 
variables across the multiple form submissions. The mechanism that Lift has for doing this is the 
Stateful Snippet 2 . A snippet that subclasses Statef ulSnippet has an extra hidden parameter 
automatically inserted into the form which ensures that during processing of that form, the same 
instance of the Statef ulSnippet will be used 3 . 

Let's look at the HTML template: 

Listing 4.5: stateful.html 

i <div id="main" class="lift : surround?with=def ault&at=content "> 

2 <div> 

3 Using stateful snippets for a better 

4 user experience 

5 </div> 

6 

7 <div> 

8 <div class=" lif t : Stateful?f orm=post "> 

9 Name: <input name="name"xbr> 

10 Age: <input name="age" value=" "><br> 

n <input type=" submit " value="Submit "> 

12 </div> 

13 </div> 

14 </div> 

The template looks pretty much like the template in onsubmit . html. Let's look at the snippet 
itself: 



Listing 4.6: Stateful.scala 



i package code 
2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import common. _ 

7 import util . Helpers ._ 

8 import scala . xml .NodeSeq 

2 There are no stateless snippets. A Stateful Snippet doesn't consume any more server-side resources than does a 
form composed via SHtml . onSubmit ( ) . Oh, and state is not a barier to scalaing. See Chapter 20. 

Earlier I talked about the security implications of hidden form parameters. The hidden parameter mechanism is not 
vulnerable to the same issues because the hidden parameter itself is just a GUID that causes a function to be invoked 
on the server. No state is exposed to the client, so there's nothing for a hacker to capture or mutate that would allow 
for the exploitation of a vulnerability. 
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9 

10 / * * 

n * A stateful snippet. The state associated with this 

12 * snippet is in instance variables 

13 */ 

w class Stateful extends StatefulSnippet { 

15 // state unique to this instance of the stateful snippet 

i6 private var name = "" 

17 private var age = "0" 

18 

19 // capture from whence the user came so we 

20 // can send them back 

21 private val whence = S.referer openOr "/" 

22 

23 // StatefulSnippet requires an explicit dispatch 

24 // to the method. 

25 def dispatch = {case "render" => render} 

26 

27 // associate behavior with each HTML element 

28 def render = 

29 "name=name" #> SHtml . text (name, name = _, "id" -> "the_name") & 

30 "name=age" #> SHtml . text (age, age = _) & 

31 "type=submit " #> SHtml . onSubmitUnit (process ) 

32 

33 // process the form 

34 private def process () = 

35 aslnt(age) match { 

36 case Full (a) if a < 13 => S.error ("Too young!") 

37 case Full (a) => { 

38 S . notice ( "Name : "+name) 

39 S .notice ("Age: "+a) 

40 S . redirectTo (whence) 

41 } 

42 

43 case _ => S.error ("Age doesn't parse as a number") 

44 } 

45 } 

There's a fair amount different here. First, the class definition: class Stateful extends 
StatefulSnippet. Because the snippet instance itself contains state, it can't be an object sin- 
gleton. It must be declared as a class so there are multiple instances. 

We capture state (name, age and from whence the user came), in instance variables. 

StatefulSnippets require a dispatch method which does method dispatching explicitly 
rather than "by-convention." 

The render method uses familiar CSS Selector Transforms to associate markup with behavior. 
However, rather than using SHtml . onSubmit, we're using SHtml .text to explicitly generate 
an HTML <input> element with both the name and value attributes set. In the case of the first 
input, we're also explicitly setting the id attribute. We're not using it in the application, but it's a 
way to demonstrate how to add extra attributes. 

Finally, the process () method attempts to covert the age Stringintoan Int. If it's an Int,but 
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less than 13, we present an error. If the String cannot be parsed to an int, we present an error, 
otherwise we do notify the user and go back to the page the user came from. 

Note in this example, we preserve the form values, so if you type something wrong in the name 
or age fields, what you typed is presented to you again. 

The big difference between the resulting HTML for StatefulSnippets and other snippets is 
the insertion of <input name="F1071441222401LO3" type="hidden" value="true"> 
in the form. This hidden field associates the snippet named "Stateful" with the instance of St ate - 
ful that was used to initially generate the form. 

Let's look at an alternative mechanism for creating a nice user experience. 

4.4 RequestVars 



i 

2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 



In this example, we're going to preserve state during the request by placing state in ReguestVars 
(see 7.8 on page 84). 

Lift has type-safe containers for state called XXXVars. There are SessionVars that have session 
scope, WizardVars that are scoped to a Wizard and ReguestVars that are scoped to the cur- 
rent request 4 . Vars are defined as singletons: private object name extends Reguest- 
Var ( " " ) . They are typed (in this case, the type is String) and they have a default value. 

So, let's look at the HTML which looks shockingly like the HTML in the last two examples: 

Listing 4.7: requestvar.html 

<div id="main" class="lift : surround?with=def ault&at=content "> 
<div> 

Using RequestVars to store state 
</div> 

<div> 

<f orm class=" lif t : ReqVar?f orm=post "> 
Name: <input name="name"xbr> 

Age: <input name="age" id="the_age" value=" 0"><br> 
<input type=" submit " value="Submit "> 
</f orm> 
</div> 
</div> 



Now, let's look at the snippet code: 



Listing 4.8: ReqVar.scala 



package code 
package snippet 

import net.liftweb. 
import http._ 
import common. _ 



In this case, "request" means full HTML page load and all subsquent Ajax operations on that page. There's also a 
Trans ientRequestVar that has the scope of the current HTTP request. 



34 CHAPTER 4. FORMS 

7 import util . Helpers ._ 

8 import scala . xml .NodeSeq 

9 

10 / * * 

ii * A RequestVar-based snippet 

12 */ 

13 object ReqVar { 

w // define RequestVar holders for name, age, and whence 

15 private object name extends RequestVar ("" ) 

i6 private object age extends RequestVar ( "0 " ) 

17 private object whence extends RequestVar (S . referer openOr "/") 

18 

19 def render = { 

20 // capture the whence... which forces evaluation of 

21 // the whence RequestVar unless it's already been set 

22 val w = whence, is 

23 

24 // we don't need an explicit function because RequestVar 

25 // extends Settable { type=String} , so Lift knows how to 

26 // get/set the RequestVar for text element creation 

27 "name=name" #> SHtml . textElem (name) & 

28 // add a hidden field that sets whence so we 

29 // know where to go 

30 "name=age" #> (SHtml . textElem (age) ++ 

31 SHtml . hidden (( ) => whence . set (w) ) ) & 

32 "type=submit " #> SHtml . onSubmitUnit (process ) 

33 } 
34 

35 // process the same way as 

36 // in Stateful 

37 private def process () = 

38 aslnt (age . is) match { 

39 case Full (a) if a < 13 => S.error ("Too young!") 

40 case Full (a) => { 

41 S . notice ( "Name : "tname) 

42 S .notice ("Age: "+a) 

43 S . redirectTo (whence) 

44 } 
45 

46 case _ => S.error ("Age doesn't parse as a number") 

47 } 

48 } 



The snippet is a singleton because the state is kept in the RequestVars. 

We use SHtml . textElem ( ) to generate the <input> tag. We can pass the RequestVar into the 
method and the function that gets/sets the RequestVar is generated for us. 

The use of this mechanism for doing stateful forms versus the StatefulSnippet mechanism is one 
of personal choice. Neither one is better, they are just different. 



Next, let's look at how to get more granular with error messages. 
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4.5 Field Errors 

In the prior examples, we displayed an error to the user. However, we didn't tell the user what 
field resulted in the error. Let's be a little more granular about error reporting. 

First, let's look at the HTML: 

Listing 4.9: fielderror.html 

i <div id="main" class=" lift : surround?with=def ault&at=content "> 

2 <div> 

3 Let's get granular about error messages 

4 </div> 

5 

6 <div> 

7 <div class="lif t : FieldErrorExample?f orm=post "> 

8 Name: <input name="name"xbr> 

9 Age: <span class="lif t :Msg?id=age&errorClass=error ">error</span> 
10 <input name="age" id="the_age" value="0"xbr> 

n <input type=" submit " value="Submit "> 

12 </div> 

13 </div> 
w </div> 

This HTML is different. Note: Age : <span class="lift :Msg?id=age&errorClass=error">error</: 
We mark an area in the markup to put the error message. 

Let's look at our snippet code which is very similar toStateful.scala with a small, but impor- 
tant difference: 



Listing 4.10: FieldErrorExample.scala 



i package code 

2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import common. _ 

7 import util . Helpers ._ 

s import scala . xml .NodeSeq 

9 

10 / * * 

ii * A StatefulSnippet like Stateful . scala 

12 */ 

13 class FieldErrorExample extends StatefulSnippet { 

14 private var name = "" 

15 private var age = "0" 

i6 private val whence = S.referer openOr "/" 

17 

is def dispatch = {case _ => render} 

19 

20 def render = 

21 "name=name" #> SHtml . text (name, name = _) & 

22 "name=age" #> SHtml . text (age, age = _) & 

23 "type=submit " #> SHtml . onSubmitUnit (process ) 
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24 

25 // like Stateful 

26 private def process () = 

27 aslnt (age) match { 

2s // notice the parameter for error corresponds to 

29 // the id in the Msg span 

30 case Full (a) if a < 13 => S . error ( "age" , "Too young!") 

31 case Full (a) => { 

32 S . notice ( "Name : "+name) 

33 S .notice ("Age: "+a) 

34 S . redirectTo (whence) 

35 } 
36 

37 // notice the parameter for error corresponds to 

38 // the id in the Msg span 

39 case _ => S . error ( "age" , "Age doesn't parse as a number") 

40 } 

41 } 

The key difference is: case Full (a) if a < 13 => S . error ( "age" , "Too young!"). 
Note that we pass "age" to S . error and this corresponds to the id in the Msg snippet in markup. 
This tells Lift how to associate the error message and the markup. 

But there's a better way to do complex forms in Lift: LiftScreen. 



4.6 LiftScreen 

Much of what we do to build web applications is generating screens that associate input with 
dynamic content. Lift provides Screen and Wizard for building single page and multi-page input 
forms with validation, back-button support, etc. 

So, let's look at the HTML for a screen: 



Listing 4.11: screen.html 



i <div id="main" class=" lift : surround?with=def ault&at=content "> 

2 <div> 

3 Let's use Lift's LiftScreen to build complex 

4 simple screen input forms. 

5 </div> 

6 

7 <div class="lif t : ScreenExample"> 

8 Put your form here 

9 </div> 
10 </div> 

We don't explicitly declare the form elements. We just point to the snippet which looks like: 

Listing 4.12: ScreenExample.scala 



i package code 
2 package snippet 
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3 

4 import net . liftweb ._ 

5 import http._ 

6 

7 / * * 

8 * Declare the fields on the screen 

9 */ 

10 object ScreenExample extends LiftScreen { 
n // here are the fields and default values 
12 val name = f ield ( "Name" , "") 

13 

14 // the age has validation rules 

15 val age = field("Age", 0, minVal(13, "Too Young")) 

16 

17 def finish ( ) { 

is S . notice ( "Name : "+name) 

19 S . notice ( "Age : "+age) 

20 } 

21 } 

In the screen, we define the fields and their validation rules and then what to do when the screen 
is finished. Lift takes care of the rest. 

The markup for generating the form, by default, is found in /templates-hidden/wizard- 
all . html. You can also select templates on a screen-by-screen basis. 



4.7 Wizard 

LiftScreen is great for single screen applications. If you've got input and validation that re- 
quires multiple screens, Wizard is what you want. We'll skip the markup 'cause it's just a snippet 
invocation. Here's the wizard code: 



Listing 4.13: WizardExample.scala 



i package code 

2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import wizard. _ 

7 import util._ 

8 

9 / * * 

io * Define the multi-page input screen 

n */ 

12 object WizardExample extends Wizard { 

13 

14 // define the first screen 

15 val screenl = new Screen { 

i6 val name = f ield ( "Name" , "") 

17 val age = field("Age", 0, minVal(13, "Too Young")) 

18 } 
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19 

20 // define the second screen 

21 val screen2 = new Screen { 

22 

23 // a radio button 

24 val rad = radio ( "Radio" , "Red", List ("Red", "Green", "Blue")) 

25 

26 // a select 

27 val sel = select ("Select", "Archer", List ( "Elwood" , "Archer", "Madeline")) 

28 

29 // want a text area. . . yeah, we got that 

30 val ta = textarea ("Text Area", "") 

31 

32 // here are password inputs with minimum lenght 

33 val pwdl = password ( "Password" , "", valMinLen(6, "Password too short")) 

34 

35 // and a custom validator 

36 val pwd2 = password ( "Password (re-enter)", "", mustMatch _) 

37 

38 // return a List [FieldError] . . . there's an implicit conversion 

39 // from String to List [FieldError] that inserts the field's ID 

40 def mustMatch (s: String) : List [FieldError] = 

41 if (s != pwdl. is) "Passwords do not match" else Nil 

42 

43 } 

44 

45 def finish ( ) { 

46 S . notice ( "Name : "+screenl . name) 

47 S . notice ( "Age : " + screenl . age) 

48 } 

49 } 

It's declarative just like the screen example above. The back button works. You can have multiple 
wizards active in multiple tabs in your browser and they don't intefer with each other. 

4.8 Ajax 

In addition to full-page HTML, Lift support Ajax forms. Because Lift's forms are functions on the 
server-side associated with GUIDs in the browser, switching a form from full page load to Ajax is, 
well, pretty trivial. Let's look at the markup: 

Listing 4.14: ajax.html 

i <div id="main" class=" lift : surround?with=def ault&at=content "> 

2 <div> 

3 An example of doing forms with Ajax. 

4 </div> 

5 

6 <form class=" lif t : f orm . a jax"> 

7 <div class=" lif t : A jaxExample"> 

8 Name: <input name="name"xbr> 

9 Age: <span class="lif t :Msg?id=age&errorClass=error ">error</spanxinput name="age" id=" 
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10 <input type=" submit " value="Submit "> 

n </div> 

12 </form> 

13 </div> 

The key difference is: <form class = "lift : f orm. a jax">. This invokes Lift's built-in form 
snippet and designates the current form as an Ajax form. Then the snippet does the following: 

Listing 4.15: AjaxExample.scala 

i package code 



2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import common. _ 

7 import util . Helpers ._ 
s import js._ 

9 import JsCmds._ 

10 import JE._ 

n import scala . xml .NodeSeq 

12 

13 / * * 



14 



■ Ajax for processing... it looks a lot like the Stateful example 
15 */ 

i6 object AjaxExample { 
17 def render = { 
is // state 

19 var name = "" 

20 var age = "0" 
val whence = S.referer openOr "/" 



40 



42 



// our process method returns a 

// JsCmd which will be sent back to the browser 

// as part of the response 

def process () : JsCmd= { 

// sleep for 400 millis to allow the user to 
// see the spinning icon 
Thread. sleep (400) 



32 // do the matching 

33 aslnt (age) match { 

34 // display an error and otherwise do nothing 
case Full (a) if a < 13 => S . error ( "age" , "Too young!"); Noop 



// redirect to the page that the user came from 
// and display notices on that page 



39 case Full (a) => 



RedirectTo (whence, () => { 



4i S . notice ( "Name : "+name) 



S. notice ("Age: "+a) 



43 }) 

44 } 



40 CHAPTER 4. FORMS 

45 

46 // more errors 

47 case _ => S . error ( "age" , "Age doesn't parse as a number"); Noop 

48 } 

49 } 
50 

51 // binding looks normal 

52 "name=name" #> SHtml . text (name, name = _, "id" -> "the_name") & 

53 "name=age" #> (SHtml . text (age, age = _) ++ SHtml . hidden (process) ) 

54 } 

55 } 

The code looks a lot like the Stateful code. Except that we don't bind to the submit button (the 
submit button is not serialized over Ajax), so we have to add a hidden field to the age field which 
does the processing. 

The process ( ) method returns a JsCmd which is the JavaScript command to send back to the 
browser in response to the Ajax form submission. In this case, we're either using S . error to 
display error notices followed by a Noop or we're doing a redirect. 

We pause for 400 milliseconds in the process ( ) method so that the user can see the spinner in 
the browser indicating that an Ajax operation is taking place. 

But the core take-away is that normal HTML processing and Ajax processing are almost identical 
and both are super-easy 



4.9 But sometimes Old Fashioned is good 

In this chapter, we've explored Lift's form building and processing features and demonstrated 
the power and value of associating GUIDs on the client with functions on the server. However, 
sometimes it's nice to have parameter processing via URL parameters... and that's easy to do with 
Lift as well. 

Every page in the examples for this chapter contain: 

i BADTAB<form action=" /query "> 

2 BADTAB <input name="q"> 

3 BADTAB <input type=" submit " value="Search"> 

4 BADTAB</form> 

This is a plain old form that generates a URL like: http : //localhost : 8 80/query?q=catf ood 
This URL can be copied, pasted, shared, etc. 

Processing this URL is easy: 

Listing 4.16: Query.scala 

i package code 
2 package snippet 

3 

4 import net . liftweb ._ 

5 import http._ 
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6 import util ._ 

7 import Helpers. _ 

8 

9 object Query { 

10 def results = ClearClearable andThen 
n "li *" #> S.param("q") . // get the query parameter 

12 toList. // convert the Box to a List 

13 flatMap (q => { 

w ("You asked: "+q) :: // prepend the query 

15 (1 to tolnt (q) ) . toList .map (_. toString) // if it can be converted to an Int 

i6 // convert it and return a sequence of Ints 

17 }) 

is } 

Using S . param ( "param_name " ) we can extract the query parameter and do something with it. 

4.10 Conclusion 

Lift's form generation and processing tools offer a wide variety of mechanisms to securely simply 
and powerfully generate and process HTML forms either as part of full HTTP requests or via Ajax 
requests. 
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Chapter 5 



HTTP and REST 



We explored Lift's HTML generation features. Let's dive down to a lower level and handle HTTP 
requests REST-style. The code for this chapter can be found at https://github.com/dpp/simply_- 
lif t / tree / master / samples / http_rest 



5.1 Introduction 

Lift gives you access to low level HTTP requests, either within the scope of an session or outside 
the scope of a session. In sessionless or stateless mode, Lift does not use the container's session 
management machinery to add a cookie to the HTTP response and does not make SessionVar 
or ContainerVar available during the request. Stateless REST requests do not require session 
affinity. Authentication for stateless REST handling can be done via OAuth. If the requests are 
handled statefully, a container session will be created if the JSESSIONID cookie is not supplied 
as part of the request and the JSESSIONID cookie will be included with the response. 

Lift makes use of Scala's pattern matching to allow you match incoming HTTP requests, extract 
values as part of the pattern matching process and return the results. Scala's pattern matching 
is very, very powerful. It allows both the declaration of a pattern that must be matched, wild- 
card values (a sub-expression may match any supplied value), wildcard values extracted into 
variables, and explicit extractors (imperative logic applied to a value to determine if it should 
match and if it does, extract it into a variable) . Lift tests a Scala PartialFunction[Req, () => 
Box [ Li f tResponse ] ] to see if it is defined for a given Req, which represents an HTTP request. 
If there is a match, Lift will take the resulting function, apply it to get a Box [LiftResponse] 
and if the Box is full, the response will be sent back to the browser. That's a mouth-full. Let's look 
at examples. 



5.2 REST the hard way 

Let's take a look at the raw level of doing REST with Lift: taking an incoming HTTP request 
and transforming it into a function that returns a Box [LiftResponse] (and don't worry, it gets 
easier, but we're starting with the ugly verbose stuff so you get an idea of what's happening under 
the covers): 

43 
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Listing 5.1: BasicExample.scala 

i package code 
2 package lib 

3 

4 import model. _ 

5 

6 import net . liftweb ._ 

7 import common. _ 
s import http._ 

9 

10 / * * 

ii * A simple example of a REST style interface 

12 * using the basic Lift tools 

13 */ 

14 object BasicExample { 

15 /* 

16 * Given a suffix and an item, make a LiftResponse 

17 */ 

is private def toResponse (suffix : String, item: Item) = 

19 suffix match { 

20 case "xml" => XmlResponse (item) 

21 case _ => JsonResponse (item) 

22 } 
23 

24 / * * 

25 * Find /simple/item/1234 . j son 

26 * Find /simple/item/1234 . xml 

27 */ 

28 lazy val findltem: Lif tRules . DispatchPF = { 

29 case Req("simple" :: "item" :: itemld :: Nil, // path 

30 suffix, // suffix 

31 GetRequest) => 

32 () => Item . find (itemld) .map (toResponse ( suffix, _) ) 

33 } 
34 

35 /** 

36 * Find /simple2/item/1234 . j son 

37 */ 

38 lazy val extractFindltem: LiftRules . DispatchPF = { 

39 // path with extractor 

40 case Req ( " simple2 " :: "item" :: Item(item) :: Nil, 

41 suffix, GetRequest) => 

42 // a function that returns the response 

43 () => Full (toResponse (suffix, item)) 

44 } 

45 } 

One additional piece of the puzzle is hooking up the handlers to Lift. This is done inBoot.scala 
with the following lines: 

i // the stateless REST handlers 

2 LiftRules . statelessDispatchTable . append (BasicExample . findltem) 

3 LiftRules . statelessDispatchTable . append (BasicExample . extractFindltem) 
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4 

5 // stateful versions of the same 

6 // LiftRules . dispatch . append (BasicExample . findltem) 

7 // LiftRules . dispatch . append (BasicExample . extractFindltem) 

Let's break down the code. First, each handler is a PartialFunction [Req, () => 
Box [LiftResponse] ], but we can use a shorthand of LiftRules . dispatchPF which is a 
Scala type that aliases the partial function. 



1 


lazy val 


findltem: Li 


.ftRules .DispatchPF = 






defines f : 


Lndltem which has the type 


signature of a 


request dispatch handler. 


1 

2 
3 


case 


Req ( " simple" 
suffix, // 
GetRequest ) 


: : "item" 
suffix 
=> 


: : itemld : 


: Nil, // path 



Defines a pattern to match. In this case, any 3 part path that has the first two parts /simple/item 
will be matched. The third part of the path will be extracted to the variable itemld. The suffix of 
the last path item will be extracted to the variable suffix and the request must be a GET. 

If the above criteria is met, then the partial function is defined and Lift will apply the partial 
function to get the resulting () => Box [LiftResponse] . 

i () => Item . find (itemld) .map (toResponse ( suffix, _) ) 

This is a function that finds the itemld and converts the resulting Item to a response based on 
the request suffix. The toResponse method looks like: 

i /* 

2 * Given a suffix and an item, make a LiftResponse 

3 */ 

4 private def toResponse (suffix : String, item: Item) = 

5 suffix match { 

6 case "xml" => XmlResponse (item) 

7 case _ => JsonResponse (item) 



That's all pretty straight forward, if a little verbose. Let's look at the other example in this file. It 
uses an extractor to convert the String of the third element of the request path to an Item: 



1 


// path with extractor 






2 


case Req ( " simple2 " :: "item" : 


: Item(item) : 


: Nil, 


3 


suffix, GetRequest) => 







In this case, the pattern will not be matched unless that third element of the path is a valid Item. 
If it is, the variable item will contain the Item for processing. Converting this to a valid response 
looks like: 

i // a function that returns the response 

2 () => Full (toResponse (suffix, item)) 
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Let's look at the object Item's unapply method to see how the extraction works: 

i / * * 

2 * Extract a String (id) to an Item 

3 */ 

4 def unapply (id: String) : Option [Item] = Item. find (id) 

In fact, let's look at the entire Item code listing. As promised, Simply Lift, does not explicitly 
cover persistence. This class is an in-memory mock persistence class, but it behaves like any other 
persistence mechanism in Lift. 

Listing 5.2: Item.scala 

i package code 

2 package model 

3 

4 import net . liftweb ._ 

5 import util._ 

6 import Helpers. _ 

7 import common. _ 
s import json._ 

9 

io import scala . xml .Node 
n 

12 /* * 

13 * An item in inventory 

14 */ 

15 case class Item(id: String, name: String, 
i6 description: String, 

17 price: BigDecimal, taxable: Boolean, 

is weight InGrams : Int, qnty: Int) 

19 

20 / * * 

21 * The Item companion object 

22 */ 

23 object Item { 

24 private implicit val formats = 

25 net . liftweb . j son . Def aultFormats + BigDecimalSerializer 

26 

27 private var items: List [Item] = parse (data) . extract [List [ Item] ] 

28 

29 private var listeners: List [Item => Unit] = Nil 

30 

31 /** 

32 * Convert a JValue to an Item if possible 

33 */ 

34 def apply(in: JValue): Box [Item] = Helpers . tryo { in . extract [ Item] } 

35 

36 /** 

37 * Extract a String (id) to an Item 

38 */ 

39 def unapply (id: String) : Option [Item] = Item. find (id) 

40 

41 /** 
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42 * Extract a JValue to an Item 

43 */ 

44 def unapply(in: JValue) : Option [Item] = apply (in) 

45 

46 / * * 

47 * The default unapply method for the case class. 

48 * We needed to replicate it here because we 

49 * have overloaded unapply methods 

50 */ 

51 def unapply(in: Any) : Option [ (String, String, 

52 String, 

53 BigDecimal, Boolean, 

54 Int, Int)] = { 

55 in match { 

56 case i: Item => Some ( (i . id, i.name, i . description, 

57 i. price, i. taxable, 

58 i . weightlnGrams, i.qnty)) 

59 case _ => None 

60 } 

61 } 
62 

63 /** 

64 * Convert an item to XML 

65 */ 

66 implicit def toXml (item: Item) : Node = 

67 <item> { Xml . toXml (item) }</item> 

68 
69 

70 / * * 

71 * Convert the item to JSON format. This is 

72 * implicit and in the companion object, so 

73 * an Item can be returned easily from a JSON call 

74 */ 

75 implicit def toJson(item: Item) : JValue = 

76 Extraction . decompose ( item) 

77 

78 / * * 

79 * Convert a Seq[Item] to JSON format. This is 
so * implicit and in the companion object, so 

si * an Item can be returned easily from a JSON call 

82 */ 

83 implicit def toJson (items : Seq[Item]) : JValue = 

84 Extraction . decompose ( items) 

85 

86 / * * 

87 * Convert a Seq[Item] to XML format. This is 

88 * implicit and in the companion object, so 

89 * an Item can be returned easily from an XML REST call 

90 */ 

91 implicit def toXml (items: Seq[Item]): Node = 

92 <items>{ 

93 items .map (toXml) 

94 }</items> 

95 
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96 / * * 

97 * Get all the items in inventory 

98 */ 

99 def inventoryltems : Seq[Item] = items 

100 

101 // The raw data 

102 private def data = 

103 " " " [ 

104 {"id": "1234", "name": "Cat Food", 

105 "description": "Yummy, tasty cat food", 

106 "price" : 4.25, 

107 "taxable": true, 

108 "weightlnGrams " : 1000, 

109 "qnty" : 4 
no } , 

in {"id": "1235", "name": "Dog Food", 

ii2 "description": "Yummy, tasty dog food", 

ii3 "price" : 7.25, 

ii4 "taxable": true, 

us "weightlnGrams": 5000, 

ii6 "qnty": 7 2 

117 } , 

118 {"id": "1236", "name": "Fish Food", 

ii9 "description": "Yummy, tasty fish food", 

120 "price" : 2 , 

121 "taxable": false, 

122 "weightlnGrams": 200, 

123 "qnty": 4 5 

124 } , 

125 {"id": "1237", "name": "Sloth Food", 

126 "description": "Slow, slow sloth food", 

127 "price" : 18.33, 
i2s "taxable": true, 

129 "weightlnGrams": 750, 

130 "qnty" : 62 

131 } , 

132 ] 

133 " " " 
134 

135 / * * 

136 * Select a random Item 

137 */ 

138 def randomltem: Item = synchronized { 

139 items (Helpers . randomlnt (items . length) ) 

140 } 

141 

142 / * * 

143 * Find an item by id 

144 */ 

145 def find (id: String) : Box [Item] = synchronized { 

146 items . find (_. id == id) 

147 } 
148 

149 / * * 
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150 * Add an item to inventory 

151 */ 

152 def add (item: Item) : Item = { 

153 synchronized { 

154 items = item :: items . filterNot (_. id == item, id) 

155 updateListeners (item) 

156 } 

157 } 
158 

159 / * * 

160 * Find all the items with the string in their name or 
i6i * description 

162 */ 

163 def search (str: String) : List [Item] = { 

164 val strLC = str . toLowerCase ( ) 

165 

166 items . filter (i => 

167 i . name . toLowerCase . indexOf ( strLC) >= | 

i6s i . description . toLowerCase . indexOf (strLC) >= 0) 

169 } 
170 

171 / * * 

172 * Deletes the item with id and returns the 

173 * deleted item or Empty if there's no match 

174 */ 

175 def delete (id: String) : Box [Item] = synchronized { 

176 var ret: Box [Item] = Empty 

177 

178 val Id = id // an upper case stable ID for pattern matching 

179 

180 items = items, filter { 

i8i case i@Item(Id, _, _, _, _, _, _) => 

182 ret = Full (i) // side effect 

183 false 

184 case _ => true 

185 } 
186 

187 ret . map (updateListeners ) 

188 } 
189 

190 / * * 

191 * Update listeners when the data changes 

192 */ 

193 private def updateListeners (item: Item) : Item = { 

194 synchronized { 

195 listeners . foreach ( f => 

196 Schedule . schedule (( ) => f(item), seconds)) 

197 

198 listeners = Nil 

199 } 

200 item 

201 } 

21)2 

203 / * * 
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204 * Add an onChange listener 

205 */ 

206 def onChange (f: Item => Unit) { 

207 synchronized { 

208 // prepend the function to the list of listeners 

209 listeners ::= f 

210 } 

211 } 

212 

213 } 
214 

215 /** 

216 * A helper that will JSON serialize BigDecimal 

217 */ 

218 object BigDecimalSerializer extends Serializer [BigDecimal] { 

219 private val Class = classOf [BigDecimal] 

220 

221 def deserialize ( implicit format: Formats) : PartialFunction [ (Typelnf o, JValue) , BigDecimal 

222 case (Typelnfo (Class, _) , json) => json match { 

223 case Jlnt(iv) => BigDecimal (iv) 

224 case JDouble (dv) => BigDecimal (dv) 

225 case value => throw new MappingException ( "Can ' t convert " + value + " to " + Class) 

226 } 

227 } 

228 

229 def serialize (implicit format: Formats) : PartialFunction [Any, JValue] = { 

230 case d: BigDecimal => JDouble (d. doubleValue) 

231 } 

232 } 



Let's take a look at what the resulting output is: 



i dpp@raptor : -/pro j/simply_lift/samples/http_rest$ curl http : //localhost : 8080/simple/item/12: 

2 { 

3 "id": "1234", 

4 "name": "Cat Food", 

5 "description" : "Yummy, tasty cat food", 

6 "price" : 4 .25, 

7 "taxable" : true, 

8 "weightlnGrams" : 1000, 

9 "qnty":4 
io } 

n 

12 dpp@raptor : -/pro j/simply_lift/samples/http_rest$ curl http : //localhost : 8080/simple/item/12: 

13 <?xml version="l . 0" encoding="UTF-8 " ?> 

14 <item> 

15 <id>1234</id> 

i6 <name>Cat Food</name> 

17 <description>Yummy, tasty cat f ood</description> 

is <price>4 . 25</price> 

19 <taxable>true</taxable> 

20 <weightInGrams>1000</weightInGrams> 

21 <qnty>4</qnty> 

22 </item> 
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23 dpp@ raptor : -/pro j /simp ly_lift /samples/ http_r est $ 



5.3 Making it easier with RestHelper 

The above example shows you how Lift deals with REST calls. However, it's a tad verbose. Lift's 
RestHelper trait contains a lot of very helpful shortcuts that make code more concise, easier to 
read and easier to maintain. Let's look at a bunch of examples and then we'll work through each 
one: 

Listing 5.3: BasicWithHelper.scala 

i package code 

2 package lib 

3 

4 import model. _ 

5 

6 import net . liftweb ._ 

7 import common. _ 
s import http._ 

9 import rest ._ 

10 import json._ 

n import scala.xml._ 

12 

13 /* * 

14 * A simple example of a REST style interface 

15 * using the basic Lift tools 

16 */ 

17 object BasicWithHelper extends RestHelper { 
is /* 

19 * Serve the URL, but have a helpful error message when you 

20 * return a 404 if the item is not found 

21 */ 

22 serve { 

23 case "simple3" :: "item" :: itemld :: Nil JsonGet _ => 

24 for { 

25 // find the item, and if it's not found, 

26 // return a nice message for the 404 

27 item <- Item . find ( itemld) ?~ "Item Not Found" 

28 } yield item: JValue 

29 

30 case "simple3" :: "item" :: itemld :: Nil XmlGet _ => 

31 for { 

32 item <- Item . find ( itemld) ?~ "Item Not Found" 

33 } yield item: Node 

34 } 
35 

36 
37 

38 serve { 

39 // Prefix notation 

40 case JsonGet ( "simple4 " :: "item" :: Item(item) :: Nil, _) => 
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41 // no need to explicitly create a LiftResponse 

42 // Just make it JSON and RestHelper does the rest 

43 item: JValue 

44 

45 // infix notation 

46 case "simple4" :: "item" :: Item(item) :: Nil XmlGet _ => 

47 item: Node 

48 } 
49 

so // serve a bunch of items given a single prefix 

51 serve ( "simple5" / "item" prefix { 

52 // all the inventory 

53 case Nil JsonGet _ => Item. inventoryltems : JValue 

54 case Nil XmlGet _ => Item. inventoryltems : Node 

55 

56 // a particular item 

57 case Item(item) :: Nil JsonGet _ => item: JValue 

58 case Item(item) :: Nil XmlGet _ => item: Node 

59 }) 
60 

61 /** 

62 * Here's how we convert from an Item 

63 * to JSON or XML depending on the request's 

64 * Accepts header 

65 */ 

66 implicit def itemToResponseByAccepts : JxCvtPF [ Item] = { 

67 case (JsonSelect, c, _) => c: JValue 

68 case (XmlSelect, c, _) => c: Node 

69 } 
70 

71 /** 

72 * serve the response by returning an item 

73 * (or a Box [Item]) and let RestHelper determine 

74 * the conversion to a LiftResponse using 

75 * the itemToResponseByAccepts partial function 

76 */ 

77 serve Jx [ Item] { 

78 case "simple6" :: "item" :: Item(item) :: Nil Get _ => item 

79 case "simple6" : : "item" : : "other" : : item : : Nil Get _ => 

so Item. find (item) ?~ "The item you're looking for isn't here" 

81 } 
82 

83 / * * 

84 * Same as the serve Jx example above, but we've 

85 * used prefixJx to avoid having to copy the path 

86 * prefix over and over again 

87 */ 

88 serve Jx [ Item] { 

89 "simple7" / "item" prefixJx { 

90 case Item (item) : : Nil Get _ => item 

91 case "other" : : item : : Nil Get _ => 

92 Item. find (item) ?~ "The item you're looking for isn't here" 

93 } 

94 } 
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95 
96 



The first thing is how we declare and register the RestHelper-based service: 

i / * * 

2 * A simple example of a REST style interface 

3 * using the basic Lift tools 

4 */ 

5 object BasicWithHelper extends RestHelper { 

Our BaseicWithHelper singleton extends the net . lift web . http . rest . RestHelper trait. 
We register the dispatch in Boot . scala: 

i Li ft Rule s . statelessDispatchTable . append (BasicWithHelper) 

This means that the whole BasicWithHelper singleton is a PartialFunction [Req, ( ) => 
Box [LiftResponse] ] that aggregates all the sub-patterns contained inside it. We defined the 
sub-patterns in a serve block which contains the pattern to match. For example: 

i serve { 

2 case "simple3" : : "item" : : itemld : : Nil JsonGet _ => 

3 for { 

4 // find the item, and if it's not found, 

5 // return a nice message for the 404 

6 item <- Item. find (itemld) ?~ "Item Not Found" 

7 } yield item: JValue 

8 

9 case "simple3" : : "item" : : itemld : : Nil XmlGet _ => 

10 for { 

n item <- Item . find ( itemld) ?~ "Item Not Found" 

12 } yield item: Node 

13 } 

Let's break this down further: 

i case "simple3" : : "item" : : itemld : : Nil JsonGet _ => 

The above matches /simple3/item/xxx where xxx is extracted to the itemld variable. The 
request must also have an Accepts header that calls for JSON. 

If the pattern matches, execute the following code: 

i for { 

2 // find the item, and if it's not found, 

3 // return a nice message for the 404 

4 item <- Item . find ( itemld) ?~ "Item Not Found" 

5 } yield item: JValue 

Some things to notice, we didn't explicitly create a function that returns a Box [LiftResponse] . 
Instead, the type is Box [JValue]. RestHelper provides implicit conversions from 
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Box[JValue] to ( ) => Box [LiftResponse] . Specifically, if the Box is a Failure, Res- 
tHelper will generate a 404 response with the Failure message as the 404's body. If the Box is 
Full, RestHelper will create a JsonResponse with the value in the payload. Let's take a look 
at the two cases: 

i dpp@raptor : -/pro j/simply_lift/samples/http_rest$ curl http : //localhost : 8080/simple3/item/i: 
2 Item Not Found 

3 

4 dpp@raptor : -/pro j/simply_lift/samples/http_rest$ curl http : //localhost : 8080/simple3/item/i: 

s { 

6 "id": "1234", 

7 "name": "Cat Food", 

8 "description" : "Yummy, tasty cat food", 

9 "price" : 4 . 25, 

10 "taxable" : true, 

n "weightlnGrams" : 1000, 

12 "qnty":4 

13 } 



The XML example is pretty much the same, except we coerse the response to Box [Node ] which 
RestHelper converts into an XmlResponse: 

1 case "simple3" :: "item" :: itemld :: Nil XmlGet _ => 

2 for { 

3 item <- Item . find ( itemld) ?~ "Item Not Found" 

4 } yield item: Node 



Which results in the following: 



i dpp@raptor : -/pro j /simply_lif t /samples/http_rest$ curl -i -H "Accept: application/xml" http 

2 HTTP/1.1 200 OK 

3 Expires: Wed, 9 Mar 2011 01:48:38 UTC 

4 Content-Length: 230 

5 Cache-Control: no-cache; private; no-store 

6 Content-Type: text/xml; charset=utf-8 

7 Pragma: no-cache 

s Date: Wed, 9 Mar 2011 01:48:38 UTC 

9 X-Lift-Version : Unknown Lift Version 

10 Server: Jetty ( 6 . 1 . 22 ) 
n 

12 <?xml version="l . 0" encoding="UTF-8 " ?> 

13 <item> 

14 <id>1234</id> 

15 <name>Cat Food</name> 

i6 <description>Yummy, tasty cat f ood</description> 

17 <price>4 . 25</price> 

is <taxable>true</taxable> 

19 <weightInGrams>1000</weightInGrams> 

20 <qnty>4</qnty> 
2i </item> 
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Okay... that's simpler because we define stuff in the serve block and the conversions from 
JValue and Node to the right response types is taken care of. Just to be explicit about where 
the implicit conversions are defined, they're in the Item singleton: 

i /** 

2 * Convert an item to XML 

3 */ 

4 implicit def toXml(item: Item) : Node = 

5 <item>{Xml . toXml (item) }</item> 

6 
7 

8 / * * 

9 * Convert the item to JSON format. This is 
10 * implicit and in the companion object, so 

n * an Item can be returned easily from a JSON call 

12 */ 

13 implicit def toJson(item: Item) : JValue = 
w Extraction . decompose ( item) 

Okay, so, yippee skippy, we can do simpler REST. Let's keep looking at examples of how we can 
make it even simpler. This example uses extractors rather than doing the explicit Item . find: 

i serve { 

2 // Prefix notation 

3 case JsonGet ( "simple4 " :: "item" :: Item(item) :: Nil, _) => 

4 // no need to explicitly create a LiftResponse 

5 // Just make it JSON and RestHelper does the rest 

6 item: JValue 

7 

8 // infix notation 

9 case "simple4" :: "item" :: Item(item) :: Nil XmlGet _ => 
10 item: Node 

ii } 



If you like DRY and don't want to keep repeating the same path prefixes, you can use prefix, for 
example: 

i // serve a bunch of items given a single prefix 

2 serve ( "simple5" / "item" prefix { 

3 // all the inventory 

4 case Nil JsonGet _ => Item. inventoryltems : JValue 

5 case Nil XmlGet _ => Item. inventoryltems : Node 

6 

7 //a particular item 

8 case Item(item) :: Nil JsonGet _ => item: JValue 

9 case Item(item) :: Nil XmlGet _ => item: Node 
io }) 

The above code will list all the items in response to /simple5/item and will serve a specific item 
in response to /simple5/item/1234, as we see in: 

i dppSraptor : -/pro j /simply_lif t/samples/http_rest$ curl http : //localhost : 8080/simple5/item 
2 [{ 
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3 "id": "1234", 

4 "name": "Cat Food", 

5 "description" : "Yummy, tasty cat food", 

6 "price" : 4 . 25, 

7 "taxable" : true, 

8 "weightlnGrams" : 1000, 

9 "qnty":4 
10 } , 

n ... 

12 , { 

13 "id": "1237", 

w "name" : "Sloth Food", 

15 "description" : "Slow, slow sloth food", 

16 "price" : 18 .33, 

17 "taxable" : true, 

is "weightlnGrams ": 750, 

19 "qnty":62 

20 }] 

21 

22 dppSraptor : -/pro j/simply_lift/samples/http_rest$ curl http : //localhost : 8080/simple5/item/i: 

23 { 

24 "id": "1237", 

25 "name" : "Sloth Food", 

26 "description" : "Slow, slow sloth food", 

27 "price" : 18 .33, 

28 "taxable" : true, 

29 "weightlnGrams ": 750, 

30 "qnty":62 

31 } 

In the above examples, we've explicitly coersed the results into a JValue or Node depending 
on the request type. With Lift, it's possible to define a conversion from a given type to response 
types (the default response types are JSON and XML) based on the request type and then define 
the request patterns to match and RestHelper takes care of the rest (so to speak.) Let's define 
the conversion from Item to JValue and Node (note the implicit keyword, that says that the 
conversion is available to serve Jx statements: 

i implicit def itemToResponseByAccepts : JxCvtPF [ Item] = { 

2 case (JsonSelect, c, _) => c: JValue 

3 case (XmlSelect, c, _) => c: Node 

4 } 

This is pretty straight forward. If it's a JsonSelect, return a JValue and if it's an XmlSelect, 
convert to a Node. 



This is used in the serve Jx statement: 



i serve Jx [ Item] { 

2 case "simple6" :: "item" :: Item(item) :: Nil Get _ => item 

'item" :: "other" :: item :: Nil Get _ => 
~ "The item you're looking for isn't here" 



3 


case "simple6" : 


4 


Item. find (item) 


5 


} 
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So /simple6/item/1234 will match and result in an Item being returned and based on the 
above implicit conversion, we turn the Item into a JValue or Node depending on the Accepts 
header and then convert that to a () => Box [Lif tResponse] . Let's see what curl has to say 
about it: 

i dpp@raptor : -/pro j/simply_lift/samples/http_rest$ curl http : //localhost : 8080/simple6/item/i; 

2 { 

3 "id": "1237", 

4 "name" : "Sloth Food", 

5 "description" : "Slow, slow sloth food", 

6 "price" : 18. 33, 

7 "taxable" : true, 

8 "weightlnGrams " : 750, 

9 "qnty":62 
io } 

n 

12 dpp@raptor : -/pro j /simply_lif t /samples/http_rest$ curl -H "Accept: application/xml" http://! 

13 <?xml version="l . 0" encoding="UTF-8 " ?> 

14 <item> 

15 <id>1234</id> 

i6 <name>Cat Food</name> 

17 <description>Yummy, tasty cat f ood</description> 

is <price>4 . 25</price> 

19 <taxable>true</taxable> 

20 <weightInGrams>1000</weightInGrams> 

21 <qnty>4</qnty> 

22 </item> 

Note also that /simple6/item/other/1234 does the right thing. This is because the path is 4 
elements long, so it won't match the first part of the pattern, but does match the second part of the 
pattern. 

Finally, let's combine serve Jx and it's DRY helper, pref ix Jx. 

1 serve Jx [ Item] { 

2 "simple7" / "item" prefixJx { 

3 case Item (item) : : Nil Get _ => item 

4 case "other" : : item : : Nil Get _ => 

5 Item. find (item) ?~ "The item you're looking for isn't here" 

6 } 

7 } 



5.4 A complete REST example 

The above code gives us the bits and pieces that we can combine into a full fledged REST service. 
Let's do that combination and see what such a service looks like: 

Listing 5.4: FullRest.scala 

i package code 
2 package lib 
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3 

4 import model. _ 

5 

6 import net . liftweb ._ 

7 import common. _ 
s import http._ 

9 import rest ._ 

10 import util._ 

n import Helpers. _ 

12 import json._ 

13 import scala.xml._ 

14 

15 /* * 

i6 * A full REST example 

17 */ 

is object FullRest extends RestHelper { 

19 

20 // Serve /api/item and friends 

21 serve ( "api" / "item" prefix { 

22 

23 // /api/item returns all the items 

24 case Nil JsonGet _ => Item. inventoryltems : JValue 

25 

26 // /api/item/count gets the item count 

27 case "count" :: Nil JsonGet _ => JInt ( Item. inventoryltems . length) 

28 

29 // /api/item/item_id gets the specified item (or a 404) 

30 case Item(item) :: Nil JsonGet _ => item: JValue 

31 

32 // /api/item/search/f oo or /api/item/search?q=f oo 

33 case "search" : : q JsonGet _ => 

34 (for { 

35 searchString <- q ::: S .params ( "q" ) 

36 item <- Item . search ( searchString) 

37 } yield item) .distinct: JValue 

38 

39 // DELETE the item in question 

40 case Item(item) :: Nil JsonDelete _ => 

41 Item, delete (item, id) . map (a => a: JValue) 

42 

43 // PUT adds the item if the JSON is parsable 

44 case Nil JsonPut Item (item) -> _ => Item. add (item) : JValue 

45 

46 // POST if we find the item, merge the fields from the 

47 // the POST body and update the item 

48 case Item(item) :: Nil JsonPost json -> _ => 

49 Item (merge Json (item, json) ) .map ( Item. add (_) : JValue) 

50 

51 // Wait for a change to the Items 

52 // But do it asynchronously 

53 case "change" : : Nil JsonGet _ => 

54 RestContinuation . async { 

55 satisfyRequest => { 

56 // schedule a "Null" return if there's no other answer 
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57 // after 110 seconds 

58 Schedule . schedule (( ) => satisfyRequest ( JNull) , 110 seconds) 

59 

60 // register for an "onChange" event. When it 

6i // fires, return the changed item as a response 

62 Item. onChange (item => satisfyRequest (item: JValue) ) 

63 } 

64 } 

65 }) 



The whole service is JSON only and contained in a single serve block and uses the prefix helper 
to define all the requests under /api/item as part of the service. 

The first couple of patterns are a re-hash of what we've already covered: 

i // /api/item returns all the items 

2 case Nil JsonGet _ => Item. inventoryltems : JValue 

3 

4 // /api/item/count gets the item count 

5 case "count" :: Nil JsonGet _ => JInt ( Item. inventoryltems . length) 

6 

7 II /api/item/item_id gets the specified item (or a 404) 

8 case Item(item) :: Nil JsonGet _ => item: JValue 

The next is a search feature at /api/item/ search. Using a little Scala library fun, we create a 
list of the request path elements that come after the search element and all the query parameters 
named q. Based on these, we search for all the Items that match the search term. We wind up with 
a List [ Item] and we remove duplicates with distinct and finally coerse the List [ Item] to 

a JValue: 

i // /api/item/search/f oo or /api/item/search?q=f oo 

2 case "search" : : q JsonGet _ => 

3 (for { 

4 searchString <- q ::: S . params ( "q" ) 

5 item <- Item . search ( searchString) 

6 } yield item) .distinct: JValue 

Next, let's see how to delete an Item: 

i // DELETE the item in question 

2 case Item(item) :: Nil JsonDelete _ => 

3 Item. delete (item. id) . map (a => a: JValue) 

The only real difference is we're looking for a JsonDelete HTTP request. 
Let's see how we add an Item with a PUT: 

i // PUT adds the item if the JSON is parsable 

2 case Nil JsonPut Item (item) -> _ => Item. add (item) : JValue 

Note the Item (item) -> _ after JsonPut. The extraction signature for JsonPut is 

(List [String] , (JValue, Req) ) . The List [String] part is simple... it's a List that 
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contains the request path. The second part of the Pair is a Pair itself that contains the JValue and 
the underlying Req (in case you need to do something with the request itself). Because there's 
a def unapply(in: JValue): Option [Item] method in the Item singleton, we can ex- 
tract (pattern match) the JValue that is built from the PUT request body. This means if the user 
PUTs a JSON blob that can be turned into an Item the pattern will match and we'll evaluate the 
right hand side of the case statement which adds the Item to inventory. That's a big ole dense pile 
of information. So, we'll try it again with POST. 

1 case Item(item) :: Nil JsonPost json -> _ => 

2 Item (mergeJson (item, json) ) .map ( Item. add (_) : JValue) 

In this case, we're match a POST on /api/item/1234 that has some parsable JSON in the POST 
body. The mergeJson method takes all the fields in the found Item and replaces them with any 
of the fields in the JSON in the POST body. So a POST body of { " qnty " : 12 3} would replace 
the qnty field in the Item. The Item is then added back into the backing store. 

Cool. So, we've got a variety of GET support in our REST service, a DELETE, PUT and POST. All 
using the patterns that RestHelper gives us. 

Now we have some fun. 

One of the features of Lift's HTML side is support for Comet (server push via long-polling.) If 
the web container supports it, Lift will automatically use asynchronous support. That means that 
during a long poll, while no computations are being performed related to the servicing of the 
request, no threads will be consumed. This allows lots and lots of open long polling clients. Lift's 
REST support includes asynchronous support. In this case, we'll demonstrate opening an HTTP 
request to /api/item/change and wait for a change to the backing store. The request will be 
satisfied with a change to the backing store or a JSON JNull after 110 seconds: 

i case "change" : : Nil JsonGet _ => 

2 RestContinuation . async { 

3 satisfyRequest => { 

4 // schedule a "Null" return if there's no other answer 

5 // after 110 seconds 

6 Schedule . schedule (( ) => satisfyRequest (JNull) , 110 seconds) 

7 

8 // register for an "onChange" event. When it 

9 // fires, return the changed item as a response 

10 Item. onChange (item => satisfyRequest (item: JValue)) 

ii } 

12 } 

If we receive a GET request to /api/item/change, invoke RestContinuation . async. We 
pass a closure that sets up the call. We set up the call by scheduling a JNull to be sent after 110 
seconds. We also register a function which is invoked when the backing store is changed. When 
either event (110 seconds elapses or the backing store changes), the functions will be invoked and 
they will apply the satif yRequest function which will invoke the continuation and send the 
response back to the client. Using this mechanism, you can create long polling services that do not 
consume threads on the server. Note too that the satisfyRequest function is fire-once so you 
can call it lots of times, but only the first time counts. 
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5.5 Wrap Up 

In this chapter, we've covered how you create web services in Lift. While there is a lot of implicit 
conversion stuff going on under the covers in RestHelper, the resulting code is pretty easy to 
read, create, and maintain. At the core, you match an incoming request against a pattern, if the 
pattern matches, evaluate the expression on the right hand side of the pattern. 
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Chapter 6 

Wiring 



Interactive web applications have many interdependent components on a single web page. For 
example (and this is the example we'll use for this chapter), you may have a shopping cart in your 
application. The shopping cart will contain items and quantities. As you add/remove items from 
the cart, the cart should update, along with the sub-total, the tax, the shipping and the grand total. 
Plus, the count of the items in the cart may be displayed on some pages without the cart contents. 
Keeping track of all of these dependencies for all the different page layouts is pretty tough work. 
When it comes to updating the site, the team must remember where all of the items are and how 
to update them and if they get one wrong, the site looks broken. 

Lift's Wiring provides a simply solution to managing complex dependencies on a single page and 
on multiple tabs. Lift's Wiring allows you to declare the formulaic relationships among cells (like a 
spreadsheet) and then the user interface components (yes, there can be more than one component) 
associated with each cell. Lift will automatically update the dependent user interface components 
based on change in the predicates. Lift will do this on initial page render and with each Ajax 
or Comet update to the page. Put another way, Wiring is like a spreadsheet and the page will 
automatically get updated when any of the predicate values change such that the change results 
in a change in the display value. 

6.1 Cells 

Like a spreadsheet, Lift's Wiring is based on Cells. Cells come in three types: ValueCell, Dy- 

namicCell, and FuncCell. 

A ValueCell contains a value that is entered by a user or depends on some user action. A 
ValueCell may represent the items in our shopping cart or the tax rate. 

A DynamicCell contains a value that changes every time the cell is accessed. For example, a 
random number or the current time. 

A FuncCell has a value based on a formula applied to the value or other cells. 

Let's see some code that demonstrates this: 

i val quantity = ValueCell (0) 

2 val price = ValueCell (Id) 

3 val total = price. lift (_ * quantity) 

63 
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We define two ValueCells, one for quantity and the other for price. Next, define the total 
by "lifting" the price in a formula that multiplies it by quantity. Let's see how it works in the 
console: 

i scala> import net . lif tweb ._ 
2 import net . lif tweb ._ 

3 

4 scala> import util._ 

5 import util._ 

6 

7 scala> val quantity = ValueCell(O) 

s quantity: net . liftweb . util . ValueCell [Int ] = ValueCell(O) 

9 

io scala> val price = ValueCell (Od) 

ii price: net . liftweb . util .ValueCell [Double ] = ValueCell (0 . 0) 

12 

13 scala> val total = price. lift (_ * quantity) 

w total: net . liftweb. util .Cell [Double] = FuncCelll (ValueCell (0 . 0) , <functionl>) 

15 

i6 scala> total. get 
17 resl: Double = 0.0 

18 

19 scala> quantity . set (10) 

20 res 2 : Int = 10 

21 

22 scala> price . set (0 . 5d) 

23 res3: Double = 0.5 

24 

25 scala> total, get 

26 res4: Double = 5.0 

Okay... pretty nifty... we can define relationships that are arbitrarily complex between Cells and 
they know how to calculate themselves. 



6.2 Hooking it up to the UI 

Now that we can declare relationships among cells, how do we associate the value of Cells with 
the user interface? 

Turns out that it's pretty simple: 

i "#total" #> WiringUI.asText (total) 

We associate the element with id="total" with a function that displays the value in total. 
Here's the method definition: 

i /** 

2 * Given a Cell register the 

3 * postPage JavaScript that will update the element with 

4 * a new value . 

5 * 
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6 * Sparam cell the cell to associate with 

7 * 

8 * @return a function that will mutate the NodeSeq (an id attribute may be added if 

9 * there's none already defined) 
10 */ 

n def asText [T] (cell : Cell[T]): NodeSeq => NodeSeq = 

Huh? that's a lot of mumbo-jumbo... what's a postPage JavaScript? 

So, here's the magic of WiringUI: Most web frameworks treat a page rendering as an event in 
time. Maybe (in the case of Seaside), there are some side effects of rendering that close over 
page rendering state such that when forms are submitted back, you get page state back. Lift 
treats a full HTML page render and subsequent Ajax requests on the page as a single event that 
has a single scope. This means that RequestVars populated during a page render are available 
during subsequent Ajax requests on that page. Part of the state that results in a page render is 
the postPage JavaScript which is a bucket of () => J sCmd or a collection of functions that 
return JavaScript. Before responding to any HTTP request associated with the page, Lift runs all 
these functions and appends the resulting JavaScript to the response sent back to the browser. 
HTTP requests associated with the page include the initial page render, subsequent Ajax request 
associated with the page and associated Comet (long poll) requests generated by the page. 

For each Cell that you wire up to the user interface, Lift captures the id of the DOM node (and 
if there's no id, Lift will assign one) and the current value of the Cell. Lift generates a function 
that looks at the current Cell value and if it's changed, Lift generates JavaScript that updates the 
DOM node with the Cell's current value. 

The result is that if an Ajax operation changes the value of a ValueCell, then all the dependent 
cells will update and the associated DOM updates will be carried back with the HTTP response. 

You have a lot of control over the display of the value. The asText method creates a 
Text (cell . toString) . However, WiringUI . apply allows you to associate a function that 
converts the Cell's type T to a NodeSeq. Further, you can control the transition in the browser 
with a jsEf feet (type signiture (String, Boolean, JsCmd) => JsCmd). There are pre- 
build jsEf f ects based on jQuery including my favorite, fade: 

i / * * 

2 * Fade out the old value and fade in the new value 

3 * using jQuery fast fade. 

4 */ 

5 def fade: (String, Boolean, JsCmd) => JsCmd = { 

6 (id: String, first: Boolean, cmd : JsCmd) => { 

7 if (first) cmd 

8 else { 

9 val sel = " jQuery ('# ' +"+id. enc Js+" ) " 

10 Run (sel+" . fadeOut (' fast ' , function () {" + 

n cmd.toJsCmd+" " + sel+" . fadeln (' fast ');})" ) 

12 } 

13 } 

14 } 

Which you can use as: 

i "#total" #> WiringUI . asText (total, JqWiringSupport . f ade) 
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Now, when the total field updates, the old value will fade out and the new value will fade in... 
cool. 



6.3 Shared Shopping 

Let's move onto a real code example. You can find this code at Shop with Me source. 

The example is going to be a simple shopping site. There are a bunch of items that you can view. 
You have a shopping cart. You can add items to the cart. If you're viewing the cart in multiple tabs 
or browser windows, the cart in all tabs/windows will update when you change the cart. Further, 
you can share your cart with someone else and any changes to the cart will be propagated to all 
the different browsers sharing the same cart. 

The data model is the same that we used in the REST chapter (see 5.2 on page 46). 

Let's look at the shopping cart definition: 

Listing 6.1: Cart.scala 

i package code 
2 package lib 

3 

4 import model. Item 

5 

6 import net . liftweb ._ 

7 import util ._ 

8 

9 / * * 

io * The shopping cart 
n */ 

12 class Cart { 

13 /** 

u * The contents of the cart 
15 */ 

i6 val contents = ValueCell [Vector [Cartltem] ] (Vector ()) 

17 

IS / * * 

19 * The subtotal 

20 */ 

21 val subtotal = contents . lift (_. foldLeft (zero) (_ + 

22 _. qMult (_. price) ) ) 

23 

24 / * * 

25 * The taxable subtotal 

26 */ 

27 val taxableSubtotal = contents . lift (_. filter (_. taxable) . 
2s foldLeft (zero) (_ + 

29 _. qMult (_. price) ) ) 

30 

31 /** 

32 * The current tax rate 

33 */ 

34 val taxRate = ValueCell (BigDecimal ( "0 . 07 ") ) 
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35 

36 /** 

37 * The computed tax 

38 */ 

39 val tax = taxableSubtotal . lift (taxRate) (_ * _) 

40 

41 / * * 

42 * The total 

43 */ 

44 val total = subtotal . lift (tax) (_ + _) 

45 

46 / * * 

47 * The weight of the cart 

48 */ 

49 val weight = contents . lift (_. foldLeft (zero) (_ + 

50 _. qMult (_. weightlnGrams ) ) ) 

51 

52 // Helper methods 

53 

54 /** 

55 * A nice constant zero 

56 */ 

57 def zero = BigDecimal (0) 

58 

59 / * * 

60 * Add an item to the cart. If it's already in the cart, 
6i * then increment the quantity 

62 */ 

63 def addltem (item: Item) { 

64 contents . atomicUpdate (v => v. find (_. item == item) match { 

65 case Some(ci) => v.map(ci => ci.copy(qnty = ci.qnty + 

66 (if (ci.item == item) 1 else 0))) 

67 case _ => v :+ Cartltem (item, 1) 

68 }) 

69 } 
70 

71 /** 

72 * Set the item quantity. If zero or negative, remove 

73 */ 

74 def setltemCnt (item: Item, qnty: Int) { 

75 if (qnty <= 0) removeltem (item) 

76 else contents . atomicUpdate (v => v. find (_. item == item) match { 

77 case Some(ci) => v.map(ci => ci. copy (qnty = 

78 (if (ci.item == item) qnty 

79 else ci . qnty) ) ) 
so case _ => v :+ Cartltem (item, qnty) 

81 }) 

82 

83 } 

84 

85 / * * 

86 * Removes an item from the cart 

87 */ 

88 def removeltem (item: Item) { 
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89 contents . atomicUpdate (_. filterNot (_. item == item)) 

90 } 

91 } 
92 

93 / * * 

94 * An item in the cart 

95 */ 

96 case class Cartltem (item: Item, qnty: Int, 

97 id: String = Helpers . nextFuncName) { 

98 

99 / * * 

ioo * Multiply the quantity times some calculation on the 

101 * contained Item (e.g., getting its weight) 

102 */ 

103 def qMult(f: Item => BigDecimal) : BigDecimal = f (item) * qnty 

104 } 
105 

106 / * * 

107 * The Cartltem companion object 

108 */ 

109 object Cartltem { 

no implicit def cartltemToItem (in : Cartltem) : Item = in. item 

in } 

Looks pretty straight forward. You've got 2 ValueCells, the cart contents and the tax rate. You've 
gota bunch of calculated Cells. At the bottom of the Cart class definition are some helper meth- 
ods that allow you to add, remove and update cart contents. We also define the Cartltem case 
class that contains the Item and the qnty (quantity). 

So far, so good. Next, let's look at the way we display all the items: 

Listing 6.2: AllltemsPage.scala 

i package code 

2 package snippet 

3 

4 import model. Item 

5 import comet. _ 

6 

7 import net . liftweb ._ 

8 import http._ 

9 import sitemap. _ 
10 import util._ 

n import Helpers. _ 

12 

13 object AllltemsPage { 

14 // define the menu item for the page that 

15 // will display all items 

i6 lazy val menu = Menu . i (" Items " ) / "item" >> 

17 Loc . Snippet (" Items " , render) 

18 

19 // display the items 

20 def render = 

2i "tbody *" #> renderltems ( Item. inventoryltems) 
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22 

23 // for a list of items, display those items 

24 def renderltems ( in : Seq[Item]) = 

25 "tr" #> in. map (item => { 

26 "a *" #> item, name & 

27 "a [href]" #> AnltemPage .menu . calcHref (item) & 

28 "@description *" #> item. description & 

29 "@price *" #> item . price . toString & 

30 "@add_to_cart [onclick] " #> 

31 SHtml . a jaxlnvoke ( ( ) => TheCart . addltem (item) ) } ) 

32 } 



We define our SiteMap entry: 



i lazy val menu = Menu . i (" Items " ) / "item" >> 
2 Loc . Snippet (" Items " , render) 



So, when the user browses to /item, they're presented with all the items in inventory. 
The template for displaying Items looks like: 

Listing 6.3: items.html 

i <table class="lift : Items"> 

2 <tbody> 

3 <tr> 

4 <td name="name"><a href="#">Name</a></td> 

5 <td name="description">Desc</td> 

6 <td name="price">$50 . 00</td> 

7 <td><button name="add_to_cart ">Add to Cart</buttonx/td> 

8 </tr> 

9 </tbody> 
10 </table> 



Next, let's look at the code for displaying an Item: 

Listing 6.4: AnltemPage. scala 



i package code 

2 package snippet 

3 

4 import model. Item 

5 import comet. _ 

6 

7 import net . liftweb ._ 

s import util._ 

9 import Helpers. _ 

10 import http._ 

n import sitemap. _ 

12 

13 import scala . xml . Text 

14 

15 object AnltemPage { 

i6 // create a parameterized page 
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17 
18 
19 

20 
21 
22 
23 
24 
25 
26 



def menu = Menu .param [ Item] ("Item", Loc . LinkText ( i => Text (i. name) 

Item. find _, _.id) / "item" / * 



} 



class AnltemPage (item: Item) { 

def render = "@name *" #> item. name & 
"Sdescription *" #> item. description & 
"Sprice *" #> item. price . toString & 
"@add_to_cart [onclick]" #> SHtml . a jaxlnvoke ( ( ) 



=> TheCart . addltem (item) ) 



This defines what happens when the user goes to /item/1234. This is more "controller-like' 
than most of the other Lift code. Let's look at the menu item definition: 



i def menu 

2 



Menu . param [ Item] ("Item", Loc . LinkText ( i => Text (i. name) 
Item. find _, _.id) / "item" / * 



We are defining a parameterized Menu entry. The parameter type is Item. That means that the 
page will display an Item and that we must be able to calculate the Item based on the request. 

"Item" is the name of the menu entry. 

Loc. LinkText (i => Text (i.name) ) takes an item and generates the display text for the 
menu entry. 

Item, find _ is a function that takes a String and converts it to Box [ Item] . It looks up the 
Item based on the parameter in the request that we're interested in. 

_. id is a function (item => String) that takes an Item and returns a String that represents 
how to build a URL that represents the Item page. This is used by "a [href] " #> Anltem- 
Page .menu . calcHref (item) to convert an Item to the HREF for the page that display the 

Item. 

Finally the URL is defined by / " item" / * which is pretty much what it looks like. It'll match 
an incoming request of the form /item/xxx and xxx is passed to the String => Box [ Item] 
function to determine the Item associated with the URL. 

So, we can display all the items. Navigate from all the items to a single item. Each item has 
a button that allows you to add the Item to the shopping cart. The Item is added to the 
cart with this code: SHtml . a jaxlnvoke (( ) => TheCart . addltem (item) )}) . The The- 
Cart . addltem ( item) can be called from anywhere in the application without regard for what 
needs to be updated when the cart is changed. 

Let's look at how the cart is displayed and managed: 

Listing 6.5: CometCart.scala 

package code 
package comet 

import lib._ 

import net . liftweb ._ 
import common. _ 



s import http. 
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9 import util ._ 

10 import js ._ 

n import js.jquery._ 

12 import JsCmds._ 

13 import scala . xml .NodeSeq 
w import Helpers. _ 

15 

16 / * * 

17 * What's the current cart for this session 
is */ 

19 object TheCart extends SessionVar (new Cart(J) 

20 

21 /* * 

22 * The CometCart is the CometActor the represents the shopping cart 

23 */ 

24 class CometCart extends CometActor { 

25 // our current cart 

26 private var cart = TheCart. get 

27 

28 / * * 

29 * Draw yourself 

30 */ 

31 def render = { 

32 "Icontents" #> ( 

33 "tbody" #> 

34 Helpers . findOrCreateld (id => // make sure tbody has an id 

35 // when the cart contents updates 

36 WiringUI . history (cart . contents ) { 

37 (old, nw, ns) => { 

38 // capture the tr part of the template 

39 val theTR = ("tr AA " #> "**■') (ns) 

40 

41 def ciToId(ci: Cartltem) : String = ci.id + "_" + ci.qnty 

42 

43 // build a row out of a cart item 

44 def html(ci: Cartltem) : NodeSeq = { 

45 ("tr [id]" #> ciToId(ci) & 

46 "@name *" #> ci.name & 

47 "@qnty *" #> SHtml . 

48 a jaxText (ci . qnty . toString, 

49 s => { 

so TheCart. 

51 set ItemCnt (ci, 

52 Helpers . tolnt (s) ) 

53 }, "style" -> "width: 20px;") & 

54 "@del [onclick]" #> SHtml. 

55 a jaxlnvoke ( ( ) => TheCart . removeltem (ci) ) ) (theTR) 

56 } 
57 

58 // calculate the delta between the lists and 

59 // based on the deltas, emit the current jQuery 

60 // stuff to update the display 

6i JqWiringSupport . calculateDeltas (old, nw, id) (ciToId _, html _) 

62 } 
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63 } ) ) & 

64 "#subtotal" #> WiringUI . asText (cart . subtotal) & // display the subttotal 

65 "#tax" #> WiringUI . asText (cart . tax) & // display the tax 

66 "ttotal" #> WiringUI . asText (cart .total) // display the total 

67 } 
68 

69 / * * 

70 * Process messages from external sources 

71 */ 

72 override def lowPriority = { 

73 // if someone sends us a new cart 

74 case SetNewCart (newCart ) => { 

75 // unregister from the old cart 

76 unregisterFromAHDepenencies () 

77 

78 // remove all the dependencies for the old cart 

79 // from the postPage JavaScript 

so theSession . clearPostPage JavaScript For ThisPage ( ) 

81 

82 // set the new cart 

83 cart = newCart 

84 

85 // do a full reRender including the fixed render piece 

86 reRender (true) 



87 



} 



89 } 
90 

91 / * * 

92 * Set a new cart for the CometCart 

93 */ 

94 case class SetNewCart (cart : Cart) 



Let's walk through the code: 



i object TheCart extends SessionVar (new CartO) 



We define a SessionVar that holds the shopping cart. 

Our CometActor captures the the current cart from the SessionVar: 

i class CometCart extends CometActor { 

2 // our current cart 

3 private var cart = TheCart. get 



Next, let's see how to draw the cart . total: 



i "#total" #> WiringUI .asText (cart .total) // display the total 

That's pretty much the way it should be. 

Let's look at the gnarly piece... how to draw or redraw the cart contents based on changes and 
only send the JavaScript the will manipulate the browser DOM to add or remove items from the 
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cart: 

i "Icontents" #> ( 

2 "tbody" #> 

3 Helpers . findOrCreateld (id => // make sure tbody has an id 

4 // when the cart contents updates 

5 WiringUI . history (cart . contents ) { 

6 (old, nw, ns) => { 

7 II capture the tr part of the template 

8 val theTR = ("tr AAn #> "**") (ns) 

9 

io def ciToId(ci: Cartltem) : String = ci.id + "_" + ci.qnty 
n 

12 // build a row out of a cart item 

13 def html(ci: Cartltem) : NodeSeq = { 
w ("tr [id]" #> ciToId(ci) & 

15 "@name *" #> ci.name & 

16 "@qnty *" #> SHtml . 

17 a jaxText (ci . qnty . toString, 

18 s => { 

19 TheCart. 

20 setltemCnt (ci, 

21 Helpers . tolnt (s) ) 

22 }, "style" -> "width: 20px;") & 

23 "@del [onclick]" #> SHtml. 

24 a jaxlnvoke ( ( ) => TheCart . removeltem (ci) ) ) (theTR) 

25 } 

26 

27 // calculate the delta between the lists and 

2s // based on the deltas, emit the current jQuery 

29 // stuff to update the display 

30 JqWiringSupport . calculateDeltas (old, nw, id) (ciToId _, html _) 

31 } 

32 })) 

First, we make sure we know the id of the <tbody> element: "tbody" #> 
Helpers . findOrCreateld (id => 

Next, wire the CometCart up to the cart . contents such that when the contents change, we 
get the old value (old), the new value (nw) and the memoized NodeSeq (the template used to do 

the rendering): WiringUI . history (cart . contents) { (old, nw, ns) => { 

Capture the part of the template associated with the <tr> element in the theTR variable: val 

theTR = ("tr AA " #> "**") (ns) 

Based on a Cartltem, return a stable id for the DOM node the represents the Cartltem: 

The html method converts a Cart Item to a NodeSeq including Ajax controls for changing quan- 
tity and removing the item from the cart. 

Finally, based on the deltas between the old list of Cartltem and the new list, generate the 
JavaScript that will manipulate the DOM by inserting and removing the appropriate DOM ele- 
ments: JqWiringSupport . calculateDeltas (old, nw, id) (ciToId _, html _) 

Next, let's see how to change the cart. If we want to share the shopping cart between two browser 
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sessions... two people shopping at their browser, but putting things in a single cart, we need a 
way to change the cart. We process the SetNewCart message to CometCart: 

i // if someone sends us a new cart 

2 case SetNewCart (newCart) => { 

3 // unregister from the old cart 

4 unregisterFromAHDepenencies ( ) 

5 

6 // remove all the dependencies for the old cart 

7 II from the postPage JavaScript 

8 theSession . clearPostPage JavaScript For ThisPage ( ) 

9 

io // set the new cart 
n cart = newCart 

12 

13 // do a full reRender including the fixed render piece 
w reRender (true) 

15 } 

There are two lines in the above code that hint at how Wiring interacts with 
Lift's Comet support: unregisterFromAHDepenencies ( ) and theSes- 

sion. clearPostPage JavaScriptFor ThisPage ( ) 

When a CometActor depends on something in WiringUI, Lift generates a weak reference be- 
tween the Cell and the CometActor. When the Cell changes value, it pokes the CometActor. 
The CometActor then updates the browser's screen real estate associated with changes to Cells. 
unregisterFromAHDepenencies ( ) disconnects the CometActor from the Cells. theSes- 
sion . clearPostPage JavaScriptForThisPage ( ) removes all the postPage JavaScript 
associated with the CometActor. Because the CometActor is not associated with a single page, 
but can appear on many pages, it has its own postPage JavaScript context. 

The final piece of the puzzle is how we share a Cart across sessions. From the UI perspective, 
here's how we display the modal dialog when the user presses the "Share Cart" button: 

Listing 6.6: Link.scala 

i package code 
2 package snippet 

3 

4 import model. _ 

5 import comet. _ 

6 import lib._ 

7 

8 import net . liftweb ._ 

9 import http._ 

io import util . Helpers ._ 

n import js ._ 

12 import JsCmds._ 

13 import js . jquery . JqJsCmds ._ 

14 

15 class Link { 

i6 // open a modal dialog based on the _share_link.html template 

17 def request = "* [onclick]" #> SHtml . a jaxlnvoke ( ( ) => { 

is (for { 
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19 template <- TemplateFinder . f indAnyTemplate (List ( "_share_link" ) ) 

20 } yield ModalDialog (template) ) openOr Noop 

21 

22 }) 

23 

24 // close the modal dialog 

25 def close = "* [onclick]" #> SHtml . a jaxlnvoke ( ( ) => Unblock) 

26 

27 // Generate the href and link for sharing 

2s def generate = { 

29 val s = ShareCart . generateLink (TheCart ) 

30 "a [href] " #> s & "a *" #> s 

31 } 

32 } 

Basically, we use jQuery's ModalDialog plugin to put a dialog up that contains a link generated 
by the ShareCart object. Let's look at ShareCart.scala: 

Listing 6.7: ShareCart.scala 

i package code 

2 package lib 

3 

4 import comet. _ 

5 

6 import net . liftweb ._ 

7 import common. _ 
s import http._ 

9 import rest . RestHelper 

10 import util._ 

n import Helpers. _ 

12 

13 // it's a RestHelper 

14 object ShareCart extends RestHelper { 

15 // private state 

i6 private var carts: Map [String, (Long, Cart)] = Map ( ) 

17 

is // given a Cart, generate a unique sharing code 

19 def codeForCart (cart : Cart) : String = synchronized { 

20 val ret = Helpers . randomString ( 12 ) 

21 

22 carts += ret -> ( 10 .minutes . later .millis -> cart) 

23 

24 ret 

25 } 
26 

27 / * -k 

2s * Generate the right link to this cart 

29 */ 

30 def generateLink (cart : Cart) : String = { 

31 S . hostAndPath + " /co_shop/ "tcodeForCart (cart ) 

32 } 
33 

34 // An extractor that converts a String to a Cart, if 
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35 // possible 

36 def unapply (code : String) : Option [Cart] = synchronized { 

37 carts . get (code) .map (_._2) 

38 } 
39 

40 // remove any carts that are 10+ minutes old 

41 private def cleanup () { 

42 val now = Helpers . millis 

43 synchronized{ 

44 carts = carts . filter { 

45 case (_, (time, _) ) => time > now 

46 } 

47 } 

48 Schedule . schedule (( ) => cleanupO, 5 seconds) 

49 } 
50 

51 // clean up every 5 seconds 

52 cleanup ( ) 

53 

54 // the REST part of the code 

55 serve { 

56 // match the incoming URL 

57 case "co_shop" :: ShareCart (cart ) :: Nil Get _ => { 

58 // set the cart 

59 TheCart . set (cart ) 

60 

6i // send the SetNewCart message to the CometCart 

62 S . session . foreach ( 

63 _. sendCometActorMessage ( "CometCart " , Empty, 

64 SetNewCart (cart) ) ) 

65 

66 // redirect the browser to / 

67 RedirectResponse ( " / " ) 

68 } 

69 } 

70 } 

The code manages the association between random IDs and Carts. If the user browses to / co_- 
shop/share_cart_id, ShareCart will set TheCart to the shared Cart and send a SetNew- 
Cart message to the CometCart instance associated with the session. 



6.4 Wrap up 

In this chapter we've seen how Lift's Wiring can be used to create complex inter-relationships 
among values and then surface those relationships in the web user interface. Wiring can be used 
with Ajax or Comet. Wiring makes it simple to build complex web pages that are user friendly 
and easy to maintain. 



Chapter 7 

Core Concepts 
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7.1 Snippets 

Lift is built on the Scala programming language. Scala is a hybrid of Functional and Object Ori- 
ented. Two core principles of functional programming languages are immutability and transfor- 
mation. 

Immutability means that once a data structure is instantiated, it will not change for its life. More 
concretely once you instantiate an object, you can freely pass the object around and the object will 
always return the same values for all its methods. Java's String class is immutable. Python 
requires immutable classes as indexes to dictionaries. Immutability is also very powerful for 
multithreaded applications because you can pass references to immutable objects across thread 
boundaries without having to worry about locking or synchronization because you are guaran- 
teed that the objects will not change state. 

7.1.1 Snippet NodeSeq => NodeSeq 

Transformation provides an alternative to "writing to a stream" for composing web pages. Rather 
than having tags that cause characters to be streamed as part of the response, Lift loads the view 
and for each "snippet" encountered in the view, Lift transforms just the markup associated with 
the snippet invocation into a new set of HTML. 

Let's make it more concrete, here's some markup: 

i <span class="foo lift : WhatTime">The time is <span id="current_time">currentTime</span></sp; 

And the associated snippet: 

i object WhatTime { 

2 def render = " #current_time" #> (new Date) .toString 

3 } 

The resulting markup will look like: 

i <span class="foo">The time is Mon Dec 06 21:01:36 PST 2010</span> 

Let's walk through how this works. First, the class attribute in the <span> has two classes, f oo 
and lif t : WhatTime. Any class attribute that starts with lif t : indicates a snippet invocation. 
A snippet is a function that transforms HTML to HTML, or in Scala, NodeSeq => NodeSeq. 

Lift looks up the snippet named WhatTime (See Section 23.1) which in this case resolves to a 
singleton and invokes the render method. The render method returns a NodeSeq => NodeSeq 
built using Lift's CSS Selector Transforms (See Section 7.10). The parameter to the function is the 
Element that caused the snippet invocation with the actual snippet invocation removed from the 
class attribute: 

i <span class=" f oo">The time is <span id="current_time">currentTime</spanx/span> 

The function is then applied and the resulting NodeSeq is inserted in the page where the origi- 
nal Element was. Because the page is composed of immutable XML objects, we can transform 
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NodeSeq => NodeSeq and not worry about anything getting changed out from under us. We 
also know that we've got valid markup through the entire page transformation process. 

Further, retaining the page as a well formed XML document allows certain tags to be put in the 
<head> tag and other tags to be inserted just before the close of the </body> tag (See Section 

7.17). 

But the simplicity of the transform is simulateously easy to understand and very powerful. 

7.1.2 Snippet instances 

The snippet could also be defined as: 

i class WhatTime { 
2 private var x = 

3 

4 def render = { 

5 X += 1 

6 " #current_time" #> ((new Date) .toString + " and you've seen this message "+x+" times) 

7 } 



7.1.3 Multiple methods on a snippet class 

7.1.4 Inter-snippet communication 

7.1.5 Recursive Snippets 

7.1.6 Snippet parameters 
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7.2 Box/Option 

Scala has a ton of nice features. One of the features that I was slow to adopt, until Burak Emir 
gently reminded me a bunch of times, is "Options". Read on about Options, Boxes, and how Lift 
makes good use of them to make clean, error resistant code. If you come from an imperative (Java, 
Ruby) background, you'll probably recognize the following code: 

i x = someOperation 

2 if Ix.nil? 

3 y = someOtherOperation 

4 if ly.nil? 

5 doSomething (x, y) return "it worked" 

6 end 

7 end 

8 return "it failed" 

Okay, so that's pseudo-code, but there are tons of operation, guard, operation, guard, blah blah 
constructs. 

Further, null/nil are passed around as failures. This is especially bad when it's null, but it's pretty 
bad when it's nil because it's not clear to the consumer of the API that there can be a "call failed" 
return value. 

In Java, null is a non-object. It has no methods. It is the exception to the statically typed rule 
(null has no class, but any reference of any class can be set to null.) Invoking a method on 
null has one and only one result: an exception is thrown, null is often returned from meth- 
ods as a flag indicating that the method ran successfully, but yielded no meaningful value. For 
example, CardHolder.findByCreditCardNumber ("2222222222") In fact, the guy who in- 
vented null called it a billion dollar mistake. 

Ruby has nil which is marginally better than null, nil is a real, singleton object. There's only 
one instance of nil in the whole system. It has methods. It is a subclass of Ob ject. Object has 
a method called "nil?" which returns false, except the nil singleton overrides this method to 
return true, nil is returned much like null in Java. It's the "no valid answer" answer. 

Scala does something different. 

There's an abstract class, called Option. Options are strongly typed. They are declared Op- 
tion [T] . This means an Option can be of any type, but once its type is defined, it does not 
change. There are two subclasses of Option: Some and None. None is a singleton (like nil). 
Some is a container around the actual answer. So, you might have a method that looks like: 

i def f indUser (name : String) : Option [User] = { 

2 val query = buildQuery (name) 

3 val resultSet = performQuery (query) 

4 val retVal = if (resultSet . next ) Some (createUser (resultSet ) ) else None 

5 resultSet . close 

6 retVal 

7 } 

Some, you've got a f indUser method that returns either Some (User) or None. So far, it doesn't 
look a lot different than our example above. So, to confuse everyone, I'm going to talk about 
collections for a minute. 
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A really nice thing in Scala (yes, Ruby has this too) is rich list operations. Rather than creating a 
counter and pulling list (array) elements out one by one, you write a little function and pass that 
function to the list. The list calls the function with each element and returns a new list with the 
values returned from each call. It's easier to see it in code: 

i scala> List(l,2,3) .map (x => x * 2) 

2 lineO : scala . List [ scala . Int ] = List (2, 4, 6) 

The above code multiplies each list item by two and "map" returns the resulting list. Oh, and you 
can be more terse, if you want: 

i scala> List(l,2,3) .map(_ * 2) 

2 line2 : scala . List [ scala . Int ] = List(2,4,6) 

You can nest map operations: 

i scala> List ( 1, 2, 3) .map (x => List (4 , 5, 6) . map (y => x * y) ) 

2 linel3: scala . List [ scala . List [ scala . Int ] ] = List (List (4, 5, 6) , List (8, 10, 12) , List (12, 15, 18) ) 

And, you can "flatten" the inner list: 

i scala> List ( 1, 2, 3) . f latMap (x => List (4, 5, 6) .map (y => x * y) ) 
2 linel4: scala . List [ scala . Int ] = List ( 4 , 5, 6, 8, 10 , 12 , 12 , 15, 18 ) 



Finally, you can "filter" only the even numbers from the first list: 



i scala> List (1, 2, 3) .filter (_ % 2 == ) . f latMap (x => List ( 4 , 5, 6) . map (y => x * y) ) 
2 linel6: scala . List [ scala . Int ] = List (8, 10, 12 ) 

But, as you can see, the map/ f latMap/ filter stuff gets pretty verbose. Scala introduced a "for" 
comprehension to make the code more readable: 

i scala> for { 

2 x <- List(l,2,3) if x % 2 == 

3 y <- List(4,5,6)} yield x * y 

4 resO: List [Int] = List (8, 10, 12) 

Okay, but what does this have to do with Opt ion [ T ] ? 

Turns out that Option implements map, f latMap, and filter (the methods necessary for the 
Scala compiler to use in the 'for' comprehension). Just as a side note, when I first encountered 
the phrase "'for' comprehension", I got scared. I've been doing programming for years and never 
heard of a "comprenhension" let alone a 'for' one. Turns out, that there's nothing fancy going on, 
but "'for' comprehension" is just a term of art for the above construct. 

So, the cool thing is that you can use this construct very effectively. The first example is simple: 

i scala> for {x <- Some (3); y <- Some (4)} yield x * y 
2 resl: Optionflnt] = Some(12) 

"That's nice, you just wrote a lot of code to multiply 3 by 4." 
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Let's see what happens if we have a "None" in there: 

i scala> val yOpt : Option [Int] = None 

2 yOpt : Option [Int] = None 

3 scala> for {x <- Some (3); y <- yOpt } yield x * y 

4 res3: Option [Int] = None 

So, we get a "None" back. How do we turn this into a default value? 

i scala> (for {x <- Some (3); y <- yOpt } yield x * y) getOrElse -1 
2 res4 : Int = -1 

i scala> (for {x <- Some (3); y <- Some (4)} yield x * y) getOrElse -1 
2 res5 : Int = 12 

Note that the "getOrElse" code is "passed by name". Put another way, that code is only executed 
if the "else" clause is valid. 

Lift has an analogous construct called Box. 

A Box can be Full or not. A non-Full Box can be the Empty singleton or a Failure. A Fail- 
ure carries around information about why the Box contains no value. 

Failure is very helpful because you can carry around information to display an error. . . an HTTP 
response code, a message, what have you. 

In Lift, I put this all together in the following way: 

• methods that return request parameters return Box[String] 

• finder methods on models (not find all, just the ones that return a single instance) return 

Box [Model] 

• any method that would have returned a null if I was writing in Java returns a Box [ T ] in Lift 

That means you get code that looks like: 

i scala> for {id <- S . param ( "id" ) ?~ "id param missing" 

2 u <- getUser(id) ?~ "User not found" 

3 } yield u.toXml 

4 res6: net . liftweb . common . Box [ scala . xml . Elem] = Failure (id param missing, Empty, Empty) 

There's no explicit guard/test to see if the "id" parameter was passed in and there's no explicit 
test to see if the user was found. 

Note also that this code is completely type-safe. While there was no explicit type declarations, the 
compiler was able to figure out what types the various objects were. 

So, let's look at the code inside a REST handler: 

i serve { 

2 case "user" : : "info" : : _ XmlGet _ => 

3 for { 
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4 id <- S . param ( " id" ) ?~ "id param missing" ~> 401 

5 u <- User . find (id) ?~ "User not found" 

6 } yield u.toXml 



If the id parameter is missing, present a nice error message and return a 401 (okay... this is ran- 
dom, but you get the point). And by default, if the user isn't found, return a 404 with the error 
that the user isn't found. 



Here's what it looks like using wget: 

i dppSbison : ~/lift_sbt_prototype$ wget http : //localhost : 8080/user/inf o . xml 

2 — 2010-06-01 15:07:27 — http : //localhost : 8080/user/inf o . xml 

3 Resolving localhost... ::1, 127.0.0.1 

4 Connecting to localhost | : : 1 | : 8080 . . . connected. 

5 HTTP request sent, awaiting response... 401 Unauthorized 

6 Authorization failed. 

7 

s dppSbison : ~/lift_sbt_prototype$ wget http : //localhost : 8080/user/inf o . xml?id=2 

9 — 2010-06-01 15:07:44 — http : //localhost : 8080/user/inf o . xml?id=2 

10 Resolving localhost... ::1, 127.0.0.1 

n Connecting to localhost | : : 1 | : 8080 . . . connected. 

12 HTTP request sent, awaiting response... 404 Not Found 

13 2010-06-01 15:07:44 ERROR 404: Not Found. 

14 

15 dppSbison : ~/lift_sbt_prototype$ wget http : //localhost : 8080/user/inf o . xml?id=l 

i6 — 2010-06-01 15:24:12 — http : //localhost : 8080/user/inf o . xml?id=l 

17 Resolving localhost... ::1, 127.0.0.1 

is Connecting to localhost | : : 1 | : 8080 . . . connected. 

19 HTTP request sent, awaiting response... 

20 200 OK Length: 274 [text/xml] Saving to: ' info .xml? id-1 ' 

21 

22 dppSbison : ~/lift_sbt_prototype$ cat inf o . xml\?id\=l 

23 <?xml version="l . 0" encoding="UTF-8 " ?> 

24 <User id="l" f irstName="Elwood" ... validated="true" superUser=" f alse"> 

25 </User> 



One more thing about Box and Option... they lead to less complex, more maintainable code. 
Even if you didn't know anything about Scala or Lift, you can read the XML serving code and the 
console exchange and figure out what happened any why it happened. This is a lot more readable 
than deeply nested if statements. And if it's readable, it's maintainable. 



I hope this is an understandable introduction to Scala's Option class and 'for' comprehension 
and how Lift makes use of these tools. 
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73 S/SHtml 

7.4 Boot 

7.5 SiteMap 

7.6 GUIDs 

A core concept in Lift is GUIDs. GUIDs are globally unique identifiers used to associate some- 
thing in the browser with a function on the server. GUIDs make Lift more secure because they 
make replay attacks very difficult and GUIDs make it easier to develop complex, stateful, interac- 
tive applications because the developer spends more time on business logic and less time on the 
plumbing of it. 

7.6.1 How GUIDs are generated 

7.6.2 Where they are used 

7.7 LiftRules 

7.8 SessionVars and RequestVars 

7.9 Helpers 
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7.10 CSS Selector Transforms 

Lift 2.2-M1 introduced a new mechanism for transforming XHTML: CSS Selector Transforms 
(CssBindFunc). The new mechanism provides a subset of CSS selectors that can be used to 
transform NodeS eq => No deSeq. Examples of this feature include: 

"iname" #> userName // replace the element with the id name with the variable user- 
Name 

"#chat_lines *" #> listOf Chats // replace the content of chat_lines with each ele- 
ment of HstOfChats 

" . pretty * " #> <b>Unicorn</b> // each element with CSS class pretty, replace con- 
tent with <b>Unicorn</b> 

"dog=cat [href]" #> "http : //dogscape . com" // set the href attribute of all ele- 
ments with the dog attribute set to cat 

"iname" #> userName & "#age" #> user Age // set name to userName and age to 
userAge 

"li *" #> userName & "li [class]" #> "foo" // set the contents of all <li> ele- 
ment with username and class to foo 

"li *" #> userName & "li [class + ] " #> "foo" // set the contents of all <li> el- 
ement with username and append foo to the class 

"*" #> <span> {userName}</span> // set all the elements to 

<span>{userName}</span> 

CSS Selector Transforms extends NodeSeq => NodeSeq... they are quite literally functions and 
can be passes as a parameter to anything expecting NodeSeq = > NodeSeq or returned as a result 
for any method that returns NodeSeq => NodeSeq. 

Let's look at each of the pieces to see how they work. 

First, you must import net . liftweb . util ._ and import Helpers ._ These packages in- 
clude the classes and the implicit conversions that make the CSS Selector Tranforms work. 

The transform is defined by: String representing selector #> transform value. 

The selector is a String constant which implements the following subset of CSS Selectors: 

• # i d - selects the element with the specified id 

• .class- selects all elements have a class attribute where one of the space-separated values 
equals class 

• attr_name=attr_value - selects all elements where the given attribute equals the given 
value 

• element_name - selects all the elements matching the name 

• * - selects all elements 
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@ name - selects all elements with the specified name 

: button - selects all the elements with type="button" 

: checkbox - selects all the elements with type="checkbox" 

: file - selects all the elements with type=" f ile" 

: password - selects all the elements with type="password" 

: radio - selects all the elements with type=" radio" 

: r e s e t - selects all the elements with t y p e = " reset" 

: submit - selects all the elements with type=" submit " 

: text - selects all the elements with type="text" 

You can put replacement rules after the selector: 

• none (e.g., " #id") replaces all matching elements with the values 

"iname" #> "David" // <span><span id="name"/x/span> -> 
<span>David</span> 

• * (e.g., "#id *") replaces the content children of the matching elements with the values 

"Iname *" #> "David" // <span><span id="name"/x/span> -> 
<span><span i d= " name >D avid</ span ></ span > 

• *+ or *< (e.g., "#id *+") appends the value to the the content children nodes 

"Iname *+" #> "David" // <span><span id="name">Name : </s- 
panx/span> -> <span><span id="name>Name : David</spanx/span> 

• - * or > * (e.g., "# id -*") prepends the value to the the content children nodes 

"Iname -*" #> "David" // <span><span id="name"> Pol- 
lak</spanx/span> -> <span><span id="name>David Pol- 
lak</spanx/span> 

• [attr] (e.g., "#id [href ]") replaces the matching attribute's value with the values. 

"#link [href]" #> "http://dogscape.com" 

// <a href="#" id="link">Dogscape</a> -> <a href ="http : //dogscape . com" 

id="link">Dogscape</a> 

• [attr+] (e.g., "#id [class + ] ") appends the value to the existing attribute. 

"span [class+]" #> "error" 

// <span class "foo">Dogscape</span> -> <span class"foo er- 
ror ">Dogs cape </span> 

• [ attr ! ] (e.g., "#id [class!]") removes the matching value to the existing from. 

"span [class!]" #> "error" 

// <span class"error f oo">Dogscape</span> -> <span 

class "foo">Dogscape</span> 
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• A A - lifts the selected element to the root of the elements that are returned making it possible 
to choose an element from a template 

• A * - lifts the selected element's children to the root of the elements that are returned making 
it possible to choose an element's children from a template 

The right hand side of the CSS Selector Transform can be one of the following: 

• String - a String constant, for example: 

"#name *" #> "David" // <span id="name"/> -> <span id="name">David</span> 
"#name *" #> getUserNameAsString 

• NodeSeg - a NodeSeq constant, for example: 

"tome *" #> <i>David</i> // <span id="name"/> -> <span 

id="name"xi>David</ix/span> 

"#name *" #> getUserNameAsHtml 

• NodeSeq => NodeSeq - a function that transforms the node (yes, it can be a CssBind- 
Func): 

"iname" #> ((n: NodeSeq) => n % ("class" -> "dog")) // <span 

id="name"/> -> <span id="name" class="dog"/> 

• Bindable - something that implements the Bindable trait (e.g., MappedField and 
Record. Field) 

• StringPromotable - A constant that can be promoted to a String (int, Symbol, Long 
or Boolean). There is an automatic (implicit) conversion from Int, Symbol, Long or Boolean 
to StringPromotable. 

"#id_like_cats" #> true & "#number_of_cats" #> 2 

• IterableConst — A Box, Seq, or Option of NodeSeq => NodeSeq, String, NodeSeq, 
or Bindable. Implicit conversions automatically promote the likes of Box [String], 
List [String], List [NodeSeq] , etc. to IterableConst. 

"#id" #> (Empty: Box[String]) // <span><span id=" id">Hi</span></span> 

-> <span/> 

"#id" #> List ("a", "b", "c") // <spanxspan id="id"/x/span> -> 

<span>abc</span> 

"#id [href]" #> (None: Option [String] ) <a id="id" href="dog"/> -> 

<a id="id"/> 

Note that if you bind to the children of a selected element, multiple copies of the element re- 
sult from bind to an IterableConst (if the element has an id attribute, the id attribute will be 
stripped after the first element): 

i "#line *" #> List ("a", "b", "c") // <li id="line>sample</li> -> 
2 // <li id="line">a</lixli>b</lixli>c</li> 

3 

4 "#age *" #> (None: Option [NodeSeq] ) // <span><span id="age">Dunno</spanx/span> -> 

5 // <span/> 
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The above use cases may seem a little strange (they are not quite orthogonal), but they address 
common use cases in Lift. * IterableFunc - A Box, Seq, or Option of functions that transform Node- 
Seq => String, NodeSeq, Seq[String], Seq[NodeSeq], Box[String], Box[NodeSeq], Option[String] or 
Option[NodeSeq]. The same rules for handling multiple values in IterableConst apply to Iterable- 
Func. Implicit conversions automatically promote the functions with the appropriate signature to 
an IterableFunc. 

You can chain CSS Selector Transforms with the & method: 

"#id" #> "33" & "#name" #> "David" & "#chat_line" #> List ("a", "b", 
"c") & ClearClearable 

CSS Selector Transforms offer an alternative to Lift's traditional binding (See Helpers, bind ( ) ). 
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7.11 Client-side behavior invoking server-side functions 

7.12 Ajax 

7.13 Comet 

7.14 LiftActor 

7.15 Pattern Matching 

7.16 Type safety 

7.17 Page rewriting 

7.18 Security 
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8.1 Localization 

Lift has broad support for localization at the page and element level. 

8.1.1 Localizing Templates 

The locale for the current request is calculated based on the function in 
LiftRules.localeCalculator. By default, the function looks at the Locale in the HTTP 
request. But you can change this function to look at the Locale for the current user by changing 

LiftRules . localeCalculator. 

When a template is requested, Lift's Tempi at eFinder looks for a template with the suf- 
fix _langCOUNTRY.html, then _lang.html, then .html. So, if you're loading /frog and 
your Locale is enUS, then Lift will look for /f rog_enUS . html, then / frog_en.html, then 
/frog. html. But if your Locale is Czech, then Lift would look for /f rog_csCZ . html, /f rog_- 
cs . html, and /frog . html. The same lookup mechanism is used for templates accessed via the 
Surround (See Section 9.14) and Embed (See Section 9.13) snippets. So, at the template level, Lift 
offers very flexible templating. 

Note: Lift parses all templates in UTF-8. Please make sure your text editor is set to UTF-8 encod- 
ing. 

8.1.2 Resource Lookup 

Lift uses the following mechanism to look up resources. Localized resources are stored in tem- 
plate files along-side your HTML pages. The same parser is used to load resources and the pages 
themselves. A global set of resources is searched for in the following files: /_resources . html, 
/ t emp 1 at es-hidden/_re sources . html, and / re sources -hidden /_re sources .html. 
Keep in mind that Lift will look for the _resources file using the suffixes based on the Locale. 

The resource file should be in the following format: 

i <resources> 

2 <res name="welcome">Benvenuto</res> 

3 <res name="thank . you">Grazie</res> 

4 <res name="locale">Localita</res> 

5 <res name="change">Cambia</res> 

6 </resources> 

In addition to global resource files, there are per-page resource files (based on the current 
Reg.) If you are currently requesting page /foo/bar, the following resource files will also 
be consulted: /f oo/_resources_bar .html, /templates-hidden/f oo/_resources_- 
bar.html, and /f oo/resources-hidden/_resources_bar . html (and all Locale-specific 
suffixes.) You can choose to create a separate resource file for each locale, or lump multiple locales 
into the _resources_bar . html file itself using the following format: 

i <resources> 

2 <res name="hello" lang="en" def ault="true">Hello</res> 

3 <res name="hello" lang="en" country="US ">Howdy, dude!</res> 
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4 <res name="hello" lang=" it ">Benvenuto</res> 

5 <res name="thank . you" lang="en" def ault="true">Thank You</res> 

6 <res name="thank . you" lang=" it ">Grazie</res> 

7 <res name="locale" lang="en" def ault="true">Locale</res> 

8 <res name="locale" lang="it ">Localita</res> 

9 <res name="change" lang="en" def ault="true">Change</res> 
10 <res name="change" lang=" it ">Cambia</res> 

li </resources> 



8.1.3 Accessing Resources 

Lift makes it easy to access resources. 

From snippets: <span class="lift : Loc . hello">This Hello will be replaced if 
possible</span> Note that the value after the . in the snippet invocation is used to look up the 
resource name. 

From code: 

• S . loc ( "hello" ) - return a Box [NodeSeq] containing the localized value for the resource 
named "hello". 

• S .??( "Hello World") - look for a resource named "Hello World" and return the String 
value for that resource. If the resource is not found, return "Hello World". 

8.1.4 Conclusion 

Lift offers a broad range of mechanisms for localizing your application on a page-by-page and 
resource-by-resource by-resource basis. 
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8.2 Dependency Injection 

Dependency injection is an important topic in the Java world. It's important because Java lacks 
certain basic features (e.g., functions) that tend to bind abstract interfaces to concrete implementa- 
tions. Basically, it's so much easier to do My Inter face thing = new Mylnterf acelmpl ( ) , 
so most developers do just that. 

Scala's cake pattern goes a long way to help developers compose complex behaviors by combining 
Scala traits. Jonas Boner wrote an excellent piece on Dependency Injection. 

The cake pattern only goes half way to giving a Java developer complete dependency injection 
functionality. The cake pattern allows you to compose the complex classes out of Scala traits, but 
the cake pattern is less helpful in terms of allowing you to make dynamic choices about which 
combination of cake to vend in a given situation. Lift provides extra features that complete the 
dependency injection puzzle. 

8.2.1 Lift Libraries and Injector 

Lift is both a web framework and a set of Scala libraries. Lift's common, actor, json, and util 
packages provide common libraries for Scala developers to build their application. Lift's libraries 
are well tested, widely used, well supported, and released on a well defined schedule (montly 
milestones, quarterly releases). 

Lift's Injector trait forms the basis of dependency injection: 

1 / * * 

2 * A trait that does basic dependency injection. 

3 */ 

4 trait Injector { 

5 implicit def inject [T] (implicit man: Manif est [T] ) : Box[T] 

6 } 

You can use this trait as follows: 

i object Mylnjector extends Injector { . . . } 

2 

3 val myThing: Box[Thing] = Mylnjector . in ject 

The reason that the instance of MyThing is in a Box is because we're not guaranteed that Myln- 
jector knows how to create an instance ofThing. Lift provides an implementation of Injector 
called Simple In ject or that allows you to register (and re-register) functions for injection: 

i object Mylnjector extends Simpleln jector 

2 

3 def buildOne() : Thing = if (testMode) new Thing with TestThingy {} else new Thing with Run1 

4 

5 Mylnjector . registerln jection (buildOne _) // register the function that builds Thing 

6 

7 val myThing: Box[Thing] = Mylnjector . in ject 
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This isn't bad... it allows us to define a function that makes the injection-time decision, and we can 
change the function out during runtime (or test-time.) However, there are two problems: getting 
Boxes for each injection is less than optimal. Further, globally scoped functions mean you have to 
put a whole bunch of logic (test vs. production vs. xxx) into the function. Simpleln jector has 
lots of ways to help out. 

i object Mylnjector extends Simpleln jector { 

2 val thing = new Inject (buildOne _) { } // define a thing, has to be a val so it's eagerly 

3 } 
4 

5 def buildOne () : Thing = if (testMode) new Thing with TestThingy {} else new Thing with Run1 

6 

7 val myThingBox: Box[Thing] = Mylnjector . in jectval 

8 

9 myThing = Mylnjector . thing . vend // vend an instance of Thing 

Inject has a futher trick up itssleave... with Inject, you can scope the function... this is helpful 
for testing and if you need to change behavior for a particular call scope: 

i Mylnjector . thing . doWith (new Thing with SpecialThing {}) { 

2 val t = Mylnjector . thing . vend // an instance of SpecialThing 

3 val bt : Box[Thing] = Mylnjector . in ject // Full (SpecialThing) 

4 } 
5 

6 Mylnjector . thing . def ault . set (( ) => new Thing with YetAnotherThing {}) // set the global sc< 

Within the scope of the doWith call, Mylnjector . thing will vend instances of SpecialThing. 
This is useful for testing as well as changing behavior within the scope of the call or globally. This 
gives us much of the functionality we get with dependency injection packages for Java. But within 
Lift WebKit, it gets better. 

8.2.2 Lift WebKit and enhanced injection scoping 

Lift's WebKit offers broad ranging tools for handling HTTP requests as well as HTML manipula- 
tion. 

Lift WebKit's Factory extends Simpleln jector, but adds the ability to scope the function 
based on current HTTP request or the current container session: 

i object Mylnjector extends Factory { 

2 val thing = new FactoryMaker (buildOne _) {} // define a thing, has to be a val so it's ea 

3 // evaluated and registered 

4 } 

5 

6 Mylnjector . thing . session . set (new Thing with ThingForSession {}) // set the instance that w: 

7 // for the duration of the session 

8 

9 Mylnjector . thing . request . set (new Thing with ThingForRequest {}) // set the instance that w: 
10 // for the duration of the request 
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WebKit's LiftRules is a Factory and many of the properties that LiftRules contains are 
FactoryMaker s. This means that you can change behavior during call scope (useful for testing): 

i LiftRules . convertToEntity . doWith (true) { ... test that we convert certain characters to en1 

Or based on the current request (for example you can change the rules for calculating the docType 
during the current request): 

i if (isMobileReqest ) LiftRules . docType . request . set ( (r : Req) => Full (DocType . xhtmlMobile) ) 

Or based on the current session (for example, changing maxConcurrentRequests based on some 
rules when a session is created): 

i if (browserlsSomethingElse) LiftRules .maxConcurrentRequests . session . set ( (r : Req) => 32) 
2 // for this session, we allow 32 concurrent requests 



8.2.3 Conclusion 

Lift's Simpleln jector/Factory facilities provide a powerful and flexible mechanism for 
vending instances based on a global function, call stack scoping, request and session scoping and 
provides more flexible features than most Java-based dependency injection frameworks without 
resorting to XML for configuration or byte-code rewriting magic. 



8.3 Modules 

Lift has supported modules from the first version of the project in 2007. Lift's entire handling of 
the HTTP request/response cycle is open to hooks. Further, Lift's templating mechanism where 
resulting HTML pages are composed by transforming page content via snippets (See Section 7.1) 
which are simply functions that take HTML and return HTML: NodeSeq => NodeSeq. Be- 
cause Lift's snippet resolution mechanism is open and any code referenced in Boot (See Section 
7.4), any code can be a Lift "module" by virtue of registering its snippets and other resources in 
LiftRules. Many Lift modules already exist including PayPal, OAuth, OpenID, LDAP, and even 
a module containing many jQuery widgets. 

The most difficult issue relating to integration of external modules into Lift is how to properly 
insert the module's menu items into a SiteMap (See Section 3.2) menu hierarchy. Lift 2.2 introduces 
a more flexible mechanism for mutating the SiteMap: SiteMap mutators. SiteMap mutators 
are functions that rewrite the SiteMap based on rules for where to insert the module's menus in 
the menu hierarchy. Each module may publish markers. For example, here are the markers for 
ProtoUser: 

i / * * 

2 * Insert this LocParam into your menu if you want the 

3 * User's menu items to be inserted at the same level 

4 * and after the item 

5 */ 

6 final case object AddUserMenusAfter extends Loc . LocParam [Any] 
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7 / * * 

s * replace the menu that has this LocParam with the User's menu 
9 * items 
10 */ 

n final case object AddUserMenusHere extends Loc . LocParam [Any] 

12 / * * 

13 * Insert this LocParam into your menu if you want the 
w * User's menu items to be children of that menu 

15 */ 

i6 final case object AddUserMenusUnder extends Loc . LocParam [Any] 

The module also makes a SiteMap mutator available, this can either be returned from the mod- 
ule's in it method or via some other method on the module. ProtoUser makes the sitemapMu- 
t at or method available which returns a SiteMap => SiteMap. 

The application can add the marker to the appropriate menu item: 

i Menu ("Home") / "index" >> User . AddUserMenusAf ter 

And when the application registers the SiteMap with Lif tRules, it applies the mutator: 

i LiftRules . setSiteMapFunc ( ( ) => User . sitemapMutator (sitemap ()) ) 



Because the mutators are composable: 



i val allMutators = User . sitemapMutator andThen FruitBat . sitemapMutator 
2 LiftRules . setSiteMapFunc (( ) => allMutators (sitemap ()) ) 

For each module, the implementation of the mutators is pretty simple: 

i private lazy val AfterUnapply = SiteMap . buildMenuMatcher (_ == AddUserMenusAf ter ) 

2 private lazy val HereUnapply = SiteMap . buildMenuMatcher (_ == AddUserMenusHere) 

3 private lazy val UnderUnapply = SiteMap . buildMenuMatcher (_ == AddUserMenusUnder) 

4 

5 /** 

6 * The SiteMap mutator function 

7 */ 

8 def sitemapMutator: SiteMap => SiteMap = SiteMap . sitemapMutator { 

9 case AfterUnapply (menu) => menu :: sitemap 
10 case HereUnapply (_) => sitemap 

n case UnderUnapply (menu) => List (menu . rebuild (_ ::: sitemap)) 

12 } (SiteMap . addMenusAtEndMutator (sitemap) ) 

We've defined some extractors that help with pattern matching. SiteMap . buildMenuMatcher 
is a helper method to make building the extractors super-simple. Then we supply a Partial- 
Function [Menu, List [Menu] ] which looks for the marker LocParam and re-writes the menu 
based on the marker. If there are no matches, the additional rule is fired, in this case, we append 
the menus at the end of the SiteMap. 
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8.4 HtmlProperties, XHTML and HTML5 

Lift unifies many aspects of parsing and displaying the HTML page in a single trait, HtmlProp- 
erties. 

HtmlProperties defines, on a session-by-session (and even a request-by-request) basis, the way 
that templates are parsed and the way that Scala's NodeSeq is converted into valid HTML output. 
The properties on HtmlProperties are: 

• docType - the DocType for the HTML page, e.g., <!DOCTYPE 
html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional/ /EN" 

"http://www.w3.org/TR/xhtmll/DTD/xhtmll-transitional.dtd"> or <! DOC- 
TYPE html> 

• encoding - the page's encoding, e.g., <?xml version="l . 0" encoding="UTF-8" ?> 

• contentType - the setting of the Content-Type response header, e.g., application/x- 
html+xml; charset=utf-8 or text/html; charset=utf-8 

• htmlOutputHeader - calculates the way to combine the docType and encoding (this is 
important for IE6 support where encoding goes after docType). 

• htmlParser -a function that converts an InputStream to a Box [NodeSeq] . This is used 
by Lift to parse templates. 

• htmlWriter -a function that writes a NodeSeq to a Writer. This is used by Lift to convert 
the internal XML representation of a page to a stream of bytes representing an HTML page. 

• html5FormsSupport - a flag indicating whether the current browser supports HTML5 
forms. 

• maxOpenRequest s - the maximum number of concurrent HTTP requests the browser sup- 
ports to a named host. 

• userAgent - the User-Agent string sent from the browser. 

8.4.1 XHTML via OldHtmlProperties 

The default properties that keep compability with the disparate LiftRules used to calculate Doc- 
Type and Encoding. Uses the PCDataXmlParser parser which requires well-formed XML files. 
Output is generally XHTML via AltXML . toXML, but cerain tags (e.g., <br>) are written in 
IE6/IE7 friendly ways. 

8.4.2 HTML5 via Html5Properties 

Prior to Lift 2.2, Lift always emitted XHTML and by default set the Content-Type header to ap- 
plication/xhtml+xml; charset=utf-8. This continues to be Lift's default behavior. It 
turns out that most browsers, even modern ones (Firefox, Chrome and Safari) had issues with 
XHTML. Further, XHTML limited the behavior of certain JavaScript libraries. 
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By invoking LiftRules .htmlProperties . default . set ( (r : Req) => new 

Html5Properties (r . userAgent ) ) in Boot.scala, you can set Lift to full HTML5 sup- 
port. Lift uses the nu.validator HTML parser and emits the correct DocType and response 
headers such that all tested browsers (IE6+, Firefox 2+, Safari 2+, Chrome 1+) render pages 
correctly. 

Because the HTML5 parser is different from the standard XML parser, you will need to adjust 
your existing templates in the following ways: 

• All tags are converted to lower case. This means the <lift :FooBar/> gets converted 
to <lift : f oobar/> I advise converting to designer friendly where possible (e.g., <div 
class = "lift :FooBar"x/div>). 

• Tags of the format <div/> and <my_thing : bind/> are not legal. They must be converted 
to <divx/div> and <my_thing:bindx/my_thing:bind>. Unfortunately, the parser 
is very forgiving so rather than barking about the lack of closing tag, the parser will nest 
things in unexpected ways. 

• There are some tags that the parser "ensures". For example a <tr>, <thead>, or <tbody> 
tag must be the first tag inside <table>. This breaks the 

<table><mysnippet : line> 

<trxtd><my snippet : bind_here>< /my snippet : bind_herex/tdx/tr> 

</mysnippet : line><table> 

paradigm. You can get the desired behavior with 

<table><tr lif t : bind=" my snippet : line"xtdxmy snippet :bind_- 
herex /my snippet :bind_herex/tdx/trxtable>. 

8.4.3 Changing behavior mid-session or mid-request 

You can change the behavior of HtmlProperties mid-session or mid-request. LiftSes- 

sion . sessionHtmlProperties is a SessionVar that contains the HtmlProperties for the 
session. Lif tSession . requestHtmlProperties is a TranientRequestVar containing the 
HtmlProperties for the request. At the begining of the request, requestHtmlProperties is 
set to the value of sessionHtmlProperties. You can alter a property for the duration of the 
request using: 

i for { 

2 session <- S. session 

3 } session . requestHtmlProperties . set ( session . 

4 requestHtmlProperties . is . setDocType (( ) => 

5 Full ("<! DOCTYPE moose>"))) 
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Chapter 9 

Built-in Snippets 

9.1 CSS 

9.2 Msgs 

9.3 Msg 

9.4 Menu 

9.5 A 

9.6 Children 

9.7 Comet 

9.8 Form 

9.9 Ignore 

9.10 Loc 

9.11 Surround 

9.12 TestCond 

9.13 Embed 

9.14 Tail 

9.15 WithParam 

9.16 Versionlnfo 
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Chapter 11 



REST 



Lift makes providing REST-style web services very simple. 
First, create an object that extends RestHelper: 



i import net . liftweb . http ._ 

2 import net . liftweb . http . rest ._ 

3 

4 object MyRest extends RestHelper 

5 

6 } 



And hook your changes up to Lift inBoot.scala: 



i LiftRules . dispatch . append (MyRest ) // stateful -- associated with a servlet container sessii 
2 LiftRules . statelessDispatchTable . append (MyRest ) // stateless — no session created 



Within your MyRest object, you can define which URLs to serve: 



i serve { 

2 case ReqC'api" :: "static" :: _, "xml", GetRequest) => <b>Static</b> 

3 case ReqC'api" :: "static" :: _, "json", GetRequest) => JString ( "Static" ) 

4 } 

The above code uses the suffix of the request to determine the response type. Lift supports testing 
the Accept header for a response type: 

i serve { 

2 case XmlGet ("api" :: "static" ::_,_) => <b>Static</b> 

3 case JsonGet ("api" :: "static" ::_,_) => JString ( "Static" ) 

4 } 

The above can also be written: 

i serve { 

2 case "api" :: "static" :: _ XmlGet _=> <b>Static</b> 

3 case "api" :: "static" :: _ JsonGet _ => JString ( "Static" ) 

4 } 

105 
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Note: If you want to navigate your Web Service, you must remember to 
add a * . xml or *.json (depending in what you have implemented) at the 

end of the URL: http : //localhost : 8080/XXX/api/static/call . json 

http: //localhost: 8 080/XXX/api/static/call . xml 

Because the REST dispatch code is based on Scala's pattern matching, we can extract elements 
from the request (in this case the third element will be extracted into the id variable which is a 
String: 

i serve { 

2 case "api" :: "user" :: id :: _ XmlGet _ => <b>ID: {id}</b> 

3 case "api" :: "user" :: id :: _ JsonGet _ => JString(id) 

4 } 

And with extractors, we convert an element to a particular type and only succeed with the pattern 
match (and the dispatch) if the parameter can be converted. For example: 

i serve { 

2 case "api" :: "user" :: AsLong(id) :: _ XmlGet _ => <b>ID: {id}</b> 

3 case "api" :: "user" :: AsLong(id) :: _ JsonGet _ => Jlnt(id) 

4 } 

In the above example, id is extracted if it can be converted to a Long. 

Lift's REST helper can also extract XML or JSON from a POST or PUT request and only dispatch the 
request if the XML or JSON is valid: 

i serve { 

2 case "api" :: "user" :: _ XmlPut xml -> _ => // xml is a scala . xml . Node 

3 User . createFromXml (xml ) .map { u => u.save; u.toXml} 

4 

5 case "api" :: "user" :: _ JsonPut json -> _ => // json is a net . lif tweb . j son . JsonAST . JVal 

6 User . createFromJson ( json) .map { u => u.save; u.toJson} 

7 } 

There may be cases when you want to have a single piece of business logic to calculate a value, 
but then convert the value to a result based on the request type. That's where serve Jx comes in 
. . . it'll serve a response for JSON and XML requests. If you define a trait called Convertable: 

i trait Convertable { 

2 def toXml: Elem 

3 def to Json: JValue 

4 } 

Then define a pattern that will convert from a Convertable to a JSON or XML: 

implicit def cvt: JxCvtPF[Convertable] = { case (JsonSelect, c, _) => c.tojson case (XmlSelect, c, _) 
=> c.toXml } 

And anywhere you use serve Jx and your pattern results in a Box [Convertable] , the cvt 
pattern is used to generate the appropriate response: 

i serveJx { 
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2 case GetC'api" :: "info" :: Info (info) :: _, _) => Full (info) 

3 } 

Or: 

i // extract the parameters, create a user 
2 // return the appropriate response 

3 

4 def addUser() : Box [Userlnfo] = 

5 for { 

6 firstname <- S . param ( " f irstname" ) ?~ "firstname parameter missing" ~> 400 

7 lastname <- S .param ( "lastname" ) ?~ "lastname parameter missing" 

8 email <- S .param ( "email" ) ?~ "email parameter missing" 

9 } yield { 

10 val u = User . create . firstName (firstname) . 
n lastName (lastname) . email (email) 

12 

13 S . param ( "password" ) foreach u .password. set 
w u . saveMe 

15 } 
16 

17 serveJx { 

is case Post("api" :: "add_user" :: _, _) => addUser() 

i" } 

In the above example, if the firstname parameter is missing, the response will be a 400 with 
the response body "firstname parameter missing". If the lastname parameter is missing, the 
response will be a 404 with the response body "lastname parameter missing". 
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Chapter 13 



From MVC 



Okay, so you're coming from MVC -land and you're used to defining routes, defining controlers 
and defining views. 

Lift is different. For HTML requests, Lift loads the view first and builds your page from the view. 
Lift also supports REST style requests for non-HTML data. (See 11 on page 105) 

"Why?" Because complex HTML pages rarely contain a dominant piece of logic... a single con- 
troller... but contain many different components. Some of those components interact and some do 
not. In Lift, you define the collection of components to be rendered in the resulting HTML page 
in the view. 

So, to create a page that has dynamic content, we need to do three things: 

• Make a SiteMap entry for the page 

• Create the view (the HTML) 

• Create the behavior (the Snippet that transforms the incoming HTML to the dynamically 
generated HTML) 

You can find the source for this project at https://github.com/dpp/simply_lift/tree/mas- 
ter / samples / f rom_mvc . 

13.1 First things first 

The first step to using Lift is to make sure you've got Java 1.6 or better installed on your machine... 
you'll need tar or zip as well. 

Download the TAR or Zip version of the Lift templates and extract the files. 

Copy the lif t_basic project into another directory called f irst_lif t. 

cd into f irst_lif t and type sbt. It will take a few minutes for sbt, the Simple Build Tool, to 
download all the depedencies. At the > prompt type update which will download Lift and every- 
thing else you need to get started. Once all that stuff is downloaded, type jetty-run and point 
your browser to http : //localhost : 8080 and you'll see a live application. To continuously 
update your running application as you to code, enter -prepare-webapp at the sbt prompt. 

Ill 
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13.2 Making a SiteMap entry 

Every page on the site needs a SiteMap entry. For more on SiteMap, see 3.2 on page 15 and 7.5 
on page 84. 

Open the Boot . scala file (src/main/scala/bootstrap/liftweb/Boot . scala) and up- 
date the SiteMap definition: 

i // Build SiteMap 

2 def sitemap () : SiteMap = SiteMap ( 

3 Menu ( "Home" ) / "index", 

4 Menu("Second Page") / "second" 
s ) 



13.3 Creating the view 

Next you have to create a file that corresponds to the path defined in the SiteMap. So, let's look 
at the src/main/webapp/index . html file: 

Listing 13.1: index.html 

i <!DOCTYPE html> 

2 <html> 

3 <head> 

4 <meta content="text/html; charset=UTF-8 " http-equiv="content-type" /> 

5 <title>Home</title> 

6 </head> 

7 <body class=" lif t : content_id=main"> 

8 <div id="main" class="lif t : surround?with=def ault&at=content "> 

9 <div> 

10 Hi, I'm a page that contains the time: 

n <span class="lif t : TimeNow">??? some time</span>. 

12 </div> 

13 

14 <div> 

15 And a button: <button class="lift : ClickMe">Click Me</button>. 



K. 



</div> 



17 </div> 

is </body> 
19 </html> 



The page is valid HTML5. <body class="lift : content_id=main"> says "ignore every- 
thing on this page except the Element with id 'main'." 

<div id="main" class="lift : surround?with=def ault&at=content "> says "Wrap 
the default page chrome around this Element." 

<span class = "lift : TimeNow">??? some time</span> says "Find the TimeNow snip- 
pet and transform this Element with the rules contained in that snippet." See 7.1 on page 78. The 
result will be <span>Fri Jan 21 11:30:34 PST 2011</span> 



13.4. CREATING THE SNIPPET 113 

So, that's simple. You tell Lift what Snippet to use to transform your static content into dynamic 
content. 



13.4 Creating the Snippet 

Next you have to tell Lift what the rules are for transforming the section of your template based on 
dynamic rules. This is a Snippet... it's a function that transforms Node Seq => NodeSeq. Let's 
look at the TimeNow snippet: 

Listing 13.2: TimeNow.scala 

i // make sure this is the snippet package so Lift 

2 // can find the snippet 

3 package code 

4 package snippet 

5 

6 // some inputs 

7 import net . liftweb ._ 
s import util._ 

9 import Helpers. _ 

10 

n // our snippet 

12 object TimeNow { 

13 // create a function (NodeSeq => NodeSeq) 
i4 // that puts the current time into the 

15 // body of the incoming Elem 

i6 def render = "* *" #> now.toString 

17 } 

This snippet must be in the snippet package so Lift knows how to find it by convention. 

It is an ob j ect which is a singleton because the snippet has no state. 

Lift calls the render method on a snippet unless you specify another method when you invoke 
your snippet. 

The snippet generates a function, NodeSeq => NodeSeq, that uses Lift's CSS Selector Trans- 
forms (See 7.10 on page 85) to insert the current time into the body of all HTML Elements: def 

render = "* *" #> now.toString 



13.5 Getting Ajaxy 

The ClickMe snippet is a little more complex, but it demonstrates, especially on the "Second 
Page" the power of Lift's View First in which no particular component on the page is the dominant 
component. Here's the ClickMe code: 

Listing 13.3: ClickMe.scala 

i // make sure this is the snippet package so Lift 

2 // can find the snippet 

3 package code 
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4 package snippet 

5 

6 // some inputs 

7 import net . liftweb ._ 

8 import util._ 

9 import Helpers. _ 
10 import http._ 

n import js.JsCmds._ 

12 

13 // our snippet 

H object ClickMe { 

15 // variables associated with the request 

i6 private object pos extends RequestVar (0) 

17 private object cnt extends RequestVar (0) 

18 

19 // create a function (NodeSeq => NodeSeq) 

20 // set the onClick method of the button 

21 def render = { 

22 // capture our position on the page 

23 val posOnPage = pos . set (pos . is + 1) 

24 

25 "button [onclick] " #> 

26 SHtml . a jaxlnvoke ( ( ) => { 

27 cnt . set (cnt . is + 1) // increment the click count 

28 Alert ( "Thanks pos: "+posOnPage+ 

29 " click count " + cnt) 

30 }) 

31 } 

32 } 

We define two RequestVars that hold request-scoped values. For Lift, the scope of a request is 
the initial full HTML page load plus any Ajax requests associated with that page. 

When the snippet's render method is called, we capture the current value for the pos Request- 
Var. 

The snippet associates the invocation of an Ajax call with the button's onclick method. When 
the button is clicked, the function is invoked. 

The function closed over the scope of the position of the button on the page. The buttons all share 
the cnt RequestVar and thus for a single page load, the number of button-presses are counted. 
If you have 5 different browser tabs open to the same page, each tab will have a unique page 
count. 

This demonstrates the component nature of Lift and why having complex items on a page means 
not having a front-controller, but having lots of behaviors associated with lots of HTML elements. 

13.6 Next Steps 

If you want to see more of Lift's snazzy Ajax and Comet, check out 2 on page 5. If you want to see 
more of the basics of SiteMap and snippets, check out 3 on page 11. If you want to see how Lift 
does forms, check out 4 on page 27. 



Part II 



Recipes 
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Chapter 14 

Dynamic html tables created from 
DB . runQuery ( ) 

14.1 Problem 

What I'm trying is: 

1. query the SQL server via DB . runQuery ( ) 

2. put the result (multiple, rows and columns) into a Table structure like this: 

i <table> 

2 <thead> 

3 <trxthx/thx/tr> 

4 </thead> 

5 <tbody> 

6 <tr><tdx/tdx/tr> 

7 </tbody> 
s </table> 

14.2 Solution 

The DB.runQuery(sql_query_string) method returns (List [String], List[List[String]]), to put that in 
a table, your view looks like: 

i <table class="lift :MySnippet "> 

2 <thead> 

3 <trxth id="my_th">Field Name</tdx/tr> 

4 </thead> 

5 <tbody> 

6 <tr id="my_tr"xtd>An item</tdx/tr> 

7 </tbody> 
s </table> 

And your snippet uses CSS Selector Transforms (See Section 7.10) and looks like: 
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i object MySnippet { 

2 def render = { 

3 val (fieldNames: List [String] , fieldValues: List [List [String] ] ) = DB . runQuery ( . . . ) 

4 

5 "#my_th *" #> fieldNames & 

6 "#my_tr *" #> fieldValues .map (values => "td *" #> values) 



Chapter 15 

Dynamically choosing content 



15.1 Problem 

I want to to keep design completely separated from logic and I am bit stuck. I have a page that 
loads different pieces of html depending on some variables and it also has some ajax code so it may 
load new pieces of html. So far, that page uses only one snippet that has the logic to decide what 
html should be loaded. So here is the question, how should the snippet get an only-with-design 
piece of html to bind data to it. 

15.2 Solution 

Snippets are evaluated recursively... this means that you can return markup from a snippet that 
contains other snippets. 

The other thing to pay attention to is the <lift : embed> snippet (See Section 9.13). 

Combining the two: 

Main page: 

i <htmlxbody> Stuff here 

2 <div class=" lift : ChooseBehavior ">Dif f erent behavior will go here</div> 

3 </bodyx/html> 

The snippet: 

i object ChooseBehavior { 

2 def render = someState match { 

3 case ShowData => <lift: embed what="_showData" /> 

4 case EditData => <lift: embed what="_editData" /> 

5 case AjaxThing => <lift: embed what="_a jaxThing" /> 

6 } 

7 } 

Then your designer need only edit the main page and each of the templates, and then you wire 
them together. 
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Chapter 16 

Ajax Forms 
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Chapter 17 

Protecting REST APIs 



17.1 Problem 

I want to expose part of my site as authenticated REST, but with custom authentication (not the 
HTTP based authentication). 

Right now, I'm thinking of using a custom dispatch, but that means I'll have to check every request 
in the request handler itself to see if it is authenticated, right? 

Authentication is just a Session Var on the server, so it also implies I need a way to pass the session 
identifier back and forth between the REST client and the service. If it were a cookie I think it 
would be transparent, but I think Lift adds te session ids to the URLs (at least that's what I see in 
my address bar). 

So, assuming I have a public "login" REST call that sets a SessionVar, how do I pass this transar- 
ently to the REST client? I have thought about a token system as well, but that seems like copying 
the session system. 

Any suggestions? 



17.2 Solution 

If you've got a: 

i object MyService extends RestHelper { 

2 .... 

3 } 

And: 

i val ensureSession : PartialFunction [Req, Unit^ 

2 case _ if isLoggedln => 

3 } 

then in Boot: 
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i import net . liftweb . util . Helpers ._ 

2 

3 LiftRules . dispatch . append (ensureSession guard MyService) 

This is a simple way to compose PartialFunctions and put a guard around all the elements 
of a PartialFunction. 



Chapter 18 



URI-based locale selection 



18.1 Problem 

I'm evaluating Lift and one thing I miss, or cannot see how toimplement, is the ability to have the 
locale determined from an URI-pattern. In Struts2 I have: 



i namespace=" / { request_locale } " 

So I can have an action (restful) invoked on an UR I = / n o / c omp a n i e s / c omp a n y / 1 and it will call 
my CompanyAction with id=l and the locale 

set to no If called from URI = / en /companies/ company /l it will callthe same CompanyAction 
but the locale will be set to "en". 

So my question is: Is it possible to teach Lift to retrieve the locale based on some uri-pattern, so 
that it will try to resolve my * . xhtml after the / { request_locale } part? 

/no/index . xhtml 

/en/index . xhtml 

Should then map to the same templates but with different locale. 

18.2 Solution 

This is an ideal use of URL rewriting. 

You have to hook up the module in Boot . scala with: UrlLocalizer . init ( ) . 
You can see a complete runnable example at DPP's GitHub Starting Point. 
Here's the code: 
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i package code 

2 package lib 

3 

4 import net . liftweb ._ 

5 import http._ 

6 import provider. _ 

7 import common. _ 

8 

9 import Java . util . Locale 

10 

n object UrlLocalizer { 

12 // capture the old localization function 

13 val oldLocalizeFunc = LiftRules . localeCalculator 

14 

15 /** 

i6 * What are the available locales? 

17 */ 

is val locales: Map [String, Locale] = 

19 Map (Locale . getAvailableLocales .map (1 => l.toString -> 1) :_*) 

20 

21 object currentLocale extends RequestVar (Locale . getDefault) 

22 

23 /** 

24 * Extract the locale 

25 */ 

26 def unapply(in: String) : Option [Locale] = 

27 if (currentLocale . set_? ) None // don't duplicate 

2s else locales . get ( in) // if it's a valid locale, it matches 

29 

30 / * * 

31 * Calculate the Locale 

32 */ 

33 def calcLocale (in : Box [HTTPRequest] ) : Locale = 

34 if (currentLocale . set_? ) currentLocale . get 

35 else oldLocalizeFunc (in) 

36 

37 / * * 

3s * Initialize the locale 

39 */ 

40 def init ( ) { 

41 // hook into Lift 

42 LiftRules . localeCalculator = calcLocale 

43 

44 // rewrite requests with a locale at the head 

45 // of the path 

46 LiftRules . statelessRewrite . append { 

47 case RewriteRequest (ParsePath (UrlLocalizer (locale) :: rest, 

is _, _, _) , _, _) => ( 

49 currentLocale . set (locale) 

so RewriteResponse (rest ) 

51 } 

52 } 

53 } 

54 } 



Chapter 19 

Embedding JavaScript in an HTML page 



19.1 Problem 

What am I doing wrong? I'm trying to output a javascript object into the page (so my front end 
guy can do some stuff with the data without parsing it out of elements by id) but it's replacing all 
the double quotes with &quot ; (only in view source - if I inspect it then firebug converts them to 
double quotes again) 

I've copied the example from EXPLORING LIFT, but it still does the same: 

i & " .data_as_object *" #> { 

2 JsCrVar ( "myOb ject" , JsOb j (( "persons " , JsArray ( 

3 JsObj ( ("name", "Thor"), ("race", "Asgard")), 

4 JsObj ( ("name", "Todd"), ("race", "Wraith")), 

5 JsObj ( ("name", "Rodney"), ("race", "Human")) 

6 )) ) ) 

Becomes: 

i 

2 { " persons" : [{ &quot ; name&quot ; : &quot ; Thor&quot ; , 

3 &quot ; race&quot ; : &quot ; Asgard&quot ; } , { &quot ; name&quot ; : 

4 " Todd" , &quot ; race&quot ; : &quot ; Wraith&quot ; } , 

5 { " name&quot ; : &quot ; Rodney&quot ; , &quot ; race&quot ; : 

6 " Human" } ] 

7 };</div> 

I've noticed that if what I'm outputting is a number rather than a string then it's fine. 

19.2 Solution 

Try: 

i & " .data_as_object *" #> { 

2 Script (JsCrVar ( "myOb ject " , JsOb j (( "persons " , JsArray ( 
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3 

4 JsObj ( ("name", "Thor"), ("race", "Asgard")), 

5 JsObj ( ("name", "Todd"), ("race", "Wraith")), 

6 JsObj ( ("name", "Rodney"), ("race", "Human")) 

7 )) ) ) ) 

JsExp are also Nodes, so they render out, but they render out escaped. Putting Script ( ) around 
them turns them into: 

i <script> 

2 // <! [CDATA[ 

3 .... 

4 ]]> 

5 </script> 



Part III 



Questions and Answers 
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Chapter 20 



Scaling 



Lift is a web framework built on the Scala programming language. Lift takes advantage of many 
of Scala's features that allow developers to very concisely code secure, scalable, highly interactive 
web applications. Lift provides a full set of layered abstractions on top of HTTP and HTML from 
"close to the metal" REST abstractions up to transportation agnostic server push (Comet) support. 
Scala compiles to JVM byte-code and is compatible with Java libraries and the Java object model. 
Lift applications are typically deployed as WAR files in J/EE web containers... Lift apps run in 
Tomcat, Jetty, Glassfish, etc. just like any other J/EE web application. Lift apps can generally 
be monitored and managed just like any Java web app. Web Applications, Sessions, and State. 
All web applications are stateful in one way or another. Even a "static" web site is made up of 
the files that are served... the application's state is defined in those files. The site content may 
be served out of a database, but the content served does not depend on identity of the user or 
anything about the HTTP request except the contents of the HTTP request. These contents can 
include the URI, parameters, and headers. The complete value of the response can be calculated 
from the request without referencing any resources except the content resources. For the purpose 
of this discussion, I will refer to these as session-less requests. News sites like the UK Guardian, 
MSNBC, and others are prototypical examples of this kind of site. Sessions. Some applications 
are customized on a user-by-user basis. These applications include the likes of Foursquare and 
others where many HTTP requests make up a "session" in which the results of previous HTTP 
requests change the behavior of future HTTP requests. Put in concrete terms, a user can log into 
a site and for some duration, the responses are specific to that user. There are many mechanisms 
for managing sessions, but the most common and secure method is creating a cryptographically 
unique token (a session id), and putting that token in the Set-Cookie response header such that 
the browser will present that Cookie in subsequent HTTP requests for a certain period of time. 
The server-side state is referenced by the Cookie and the state is made available to the web appli- 
cation during the scope of servicing the request and any mutations the web app makes to session 
state during the request are kept on the server and are available to the application in subsequent 
requests. Another available technique for managing state is to serialize application state in the 
Cookie and deliver it to the browser such that the server is not responsible for managing state 
across requests. As we've recently discovered, this is a tremendously insecure way to manage 
application state. Further, for any moderately complex application, the amount of data the needs 
to be transferred as part of each request and response is huge. Migratory Sessions. Many web 
application managers allow for server-managed sessions to migrate across a cluster of web appli- 
cation servers. In some environments such as Ruby on Rails, this is a hard requirement because 
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only one request at a time can be served per process, thus for any moderate traffic site, there 
must be multiple processes serving pages. There are many strategies for migrating state across 
processes: storing state on disk, in memcached, in a database (relational or NoSQL), or having 
some proprietary cluster communications protocol. In any of these scenarios sessions can migrate 
across the grid of processes serving requests for a given web application. Web applications that 
support migratory state are often referred to as "stateless" because the session state does not re- 
side in the same process as the web application. Session Affinity. Some applications require that 
all requests related to a particular session are routed to the same process and that process keeps 
session-related content in local memory. In a cluster, there are multiple mechanisms for achiev- 
ing session affinity... the two most popular being HAProxy and Nginx. Availability, Scalability, 
Security, Performance, and User Experience. There are many vectors on which to measure the 
overall-quality of a web application. Let's take a quick peek at each one. Availability. Avail- 
ability of an application is the amount of time it gives a meaningful response to a request. Highly 
available applications generally span multiple pieces of hardware and often multiple data centers. 
Highly available applications are also typically available during upgrades of part of the system 
that makes up the application. Highly available applications have very few single points of failure 
and those single points of failure are usually deployed on very reliable hardware. Scalability. A 
scalable application can, within certain bounds, respond with similar performance to increased 
load by adding hardware to process more load. No system is infinitely or linearly scalable. How- 
ever, many systems have grossly disproportionate load demands such that, for example, you can 
add a lot of web application front-ends to a Rails application before there's enough load on the 
back-end RDBMS such that scaling is impaired. 

Security. The Internet is a dangerous place and no request that is received from the Internet can 
be trusted. Applications, frameworks, systems and everything else must be designed to be se- 
cure and resist attacks. The most common attacks on web application are listed in the OWASP 
Top Ten. Performance. Web application performance can be measured on two vectors: response 
time to a request and system resources required to service the request. These two vectors are 
inter-dependent. User Experience. The user experience of a web app is an important measure of 
its quality. User experience can be measured on many different vectors including perceived re- 
sponsiveness, visual design, interactivity, lack of "hicups", etc. Ultimately, because we're building 
applications for users, the user experience is very important. Lift's trade-offs. Given the number 
and complexity related to the quality of a web application, there are a lot of trade-offs, implicit 
and explicit, to building a framework that allows developers and business people to deliver a 
great user experience. Let's talk for a minute about what Lift is and what it isn't. Lift is a web 
framework. It provides a set of abstractions over HTTP and HTML such that developers can write 
excellent web applications. Lift is persistence agnostic. You can use Lift with relational databases, 
file systems, NoSQL data stores, mule carts, etc. As long as you can materialize an object into 
the JVM where Lift is running, Lift can make use of that object. Lift sits on top of the JVM. Lift 
applications execute in the Java Virtual Machine. The JVM is a very high performance computing 
system. There are raging debates as to the relative performance of JVM code and native machine 
code. No matter which benchmarks you look at, the JVM is a very fast performer. Lift apps take 
advantage of the JVM's performance characteristics. Moderately complex Lift apps that access the 
database can serve 1,000+ requests per second on quad-core Intel hardware. Even very complex 
Lift apps that make many back-end calls per request can serve hundreds of requests per second on 
EC2 large instances. Lift as proxy. Many web applications, typically REST applications, provide 
a very thin layer on top of a backing data store. The web application serves a few basic functions 
to broker between the HTTP request and the backing store. These functions include: request and 



133 

parameter validation, authentication, parameter unpacking, back-end service request, and trans- 
lation of response data to wire format (typically XML or JSON). Lift can service these kinds of 
requests within the scope of a session or without any session at all, depending on application 
design. For more information on Lift's REST features, see Lift RestHelper. When running these 
kinds of services, Lift apps can be treated without regard for session affinity. Lift as HTML gen- 
erator. Lift has a powerful and secure templating mechanism. All Lift templates are expressed 
as valid XML and during the rendering process, Lift keeps the page in XML format. Pages ren- 
dered via Lift's templating mechanism are generally resistant to cross site scripting attacks and 
other attacks that insert malicious content in rendered pages. Lift's templating mechanism is de- 
signer friendly yet supports complex and powerful substitution rules. Further, the rendered page 
can be evaluated and transformed during the final rendering phase to ensure that all script tags 
are at the bottom of the page, all CSS tags are at the top, etc. Lift's templating mechanism can 
be used to serve sessionless requests or serve requests within the context of a session. Further, 
pages can be marked as not requiring a session, yet will make session state available if the re- 
quest was made in the context of a container session. Lift page rendering can even be done in 
parallel such that if there are long off-process components on the page (e.g., advertising servers), 
those components can be Sessionless Lift, forms and Ajax Lift applications can process HTML 
forms and process Ajax requests even if there's no session associated with the request. Such forms 
and Ajax requests have to have stable field names and stable URLs, but this is the same require- 
ment as most web frameworks including Struts, Rails, and Django impose on their applications. 
In such a mode, Lift apps have the similar characteristics to web apps written on tops of Struts, 
Play, JSF and other popular Java web frameworks. Lift as Secure, Interactive App Platform Lift 
features require session affinity: GUID to function mapping, type-safe SessionVars and Comet. 
Applications that take advantage of these features need to have requests associated with the JVM 
that stores the session. I'll discuss the reason for this limitation, the down-side to the limitation, 
the downside to migratory session, and the benefits of these features. Application servers that 
support migratory sessions (sessions that are available to application servers running in multiple 
address spaces/processes) require a mechanism for transferring the state information between 
processes. This is typically (with the exception of Terracotta) done by serializing the stored data. 
Serialization is the process of converting rich data structures into a stream of bytes. Some of 
Scala's constructs are hard or impossible to serialize. For example, local variables that are mu- 
tated within a closure are promoted from stack variables to heap variables. When those variables 
are serialized at different times, the application winds up with two references even though the 
references are logically the same. Lift makes use of many of these constructs (I'll explain why 
next) and Lift's use of these constructs makes session serialization and migration impossible. It 
also means that Lift's type-safe SessionVars are not guaranteed to be serialized. One of the key 
Lift constructs is to map a cryptographically unique identifier in the browser to a function on the 
server. Lift uses Scala functions which close over scope, including all of the variables referenced 
by the function. This means that it's not necessary to expose primary keys to the client when edit- 
ing a record in the database because the primary key of the record or the record itself is known 
to the function on the server. This guards against OWASP Vulnerability A4, Insecure Object Ref- 
erences as well as Replay Attacks. From the developer's standpoint, writing Lift applications is 
like writing a VisualBasic application... the developer associates the user action with a function. 
Lift supplies the plumbing to bridge between the two. Lift's GUID to function mapping extends 
to Lift's Ajax support. Associating a button, checkbox, or other HTML element with an Ajax call 
is literally a single line: SHtml.ajaxButton(<b>PressMe</b>, () => Alert("You pressed a button at 
"+Helpers.currentTimeFormatted) Lift's Ajax support is simple, maintainable, and secure. There's 
no need to build and maintain routing. Lift has the most advanced server-push/Comet support 
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of any web framework or any other system currently available. Lift's comet support relies on 
session affinity. Lift's comet support associates an Actor with a section of screen real estate. A 
single browser window may have many pieces of screen real estate associated with many of Lift's 
CometActors. When state changes in the Actor, the state change is pushed to the browser. Lift 
takes care of multiplexing a single HTTP connection to handle all the comet items on a given 
page, the versioning of the change deltas (if the HTTP connection is dropped while 3 changes 
become available, all 3 of those changes are pushed when the next HTTP request is made.) Fur- 
ther, Lift's comet support will work the same way once web sockets are available to the client and 
server... there will be no application code changes necessary for web sockets support. Lift's comet 
support requires that the connect is made from the browser back to the same JVM in which the 
CometActors are resident... the same JVM where the session is located. 

The downside to Lift's session affinity requirement mainly falls on the operations team. They 
must use a session aware load balancer or other mechanism to route incoming requests to the 
server that the session is associated with. This is easily accomplished with HAProxy and Nginx. 
Further, if the server running a given session goes down, the information associated with that 
session is lost (note that any information distributed off-session [into a database, into a cluster of 
Akka actors, etc.] is preserved.) But, Lift has extended session facilities that support re-creation 
of session information in the event of session lost. Lift also has heart-beat functionality so that 
sessions are kept alive as long as a browser page is open to the application, so user inactivity will 
not result in session timeouts. 

Compared to the operational cost of a session aware load balancer, there are many costs associated 
with migratory sessions. First, there must be a persistence mechanism for those sessions. Mem- 
cached is an unreliable mechanism as memcached instances have no more stability than the JVM 
which hosts the application and being a cache, some sessions may get expired. Putting session 
data in backing store such as MySQL or Cassandra increases the latency of requests. Further, the 
costs of serializing state, transmitting the state across the network, storing it, retrieving it, trans- 
mitting it across the network, and deserializing it all costs a lot of cycles and bandwidth. When 
your Lift application scales beyond a single server, beyond 100 requests per second, the costs of 
migrating state on every request becomes a significant operational issue. 

Session serialization can cause session information loss in the case of multiple requests being ex- 
ecuted in multiple processes. It's common to have multiple tabs/windows open to the same ap- 
plication. If session data is serialized as a blob and two different requests from the same server 
are being executed at the same time, the last request to write session data into the store will over- 
write the prior session data. This is a concurrency problem and can lead to hard to debug issues 
in production because reproducing this kind of problem is non-trivial and this kind of problem is 
not expected by developers. 

The third issue with migratory sessions and session serialization is that the inability to store com- 
plex information in the session (e.g., a function that closes over scope) means that the developer 
has to write imperative code to serialize session state to implement complex user interactions like 
multi-screen wizards (which is a 400 line implementation in Lift). These complex, hand written 
serializations are error prone, can introduce security problems and are non-trivial to maintain. 

The operational costs of supporting session affinity are not materially different from the opera- 
tional costs of providing backing store for migratory sessions. On the other hand, there are many 
significant downsides to migratory sessions. Let's explore the advantages of Lift's design. 

Lift's use of GUIDs associated with functions on the server: Increase the security of the applica- 
tion by guarding against cross site request forgeries, replay attacks, and insecure object references 
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Decrease application development and maintenance time and costs Increase application inter- 
activity, thus a much better user experience Increase in application richness because of simpler 
Ajax, multi-page Wizards, and Comet Improved application performance because fewer cycles 
are spent serializing and transmitting session information No difference in scalability... just add 
more servers to the front end to scale the front end of your application The positive attributes of 
Lift's design decisions are evident at Foursquare which handles thousands of requests per second 
all served by Lift. There are very few sites that have more traffic than Foursquare. They have 
scaled their web front end successfully and securely with Lift. Other high volume sites including 
Novell are successfully scaling with Lift. If you are scaling your site, there are also commercial Lift 
Cloud manager tools that can help manage clusters of Lift's session requirements. Conclusion Lift 
provides a lot of choices for developing and deploying complex web applications. Lift can operate 
in a web container like any other Java web framework. If you choose to use certain Lift features 
and you are deploying across multiple servers, you need to have a session aware load balancer. 
Even when using Lift's session-affinity dependent features, Lift applications have higher perfor- 
mance, identical availability, identical scalability, better security, and better user experience than 
applications written with web frameworks such as Ruby on Rails, Struts, and GWT. 
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Chapter 21 

How Lift does function/GUID mapping 
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Chapter 22 



How Lift does Comet 



I can speak to Lift's Comet Architecture which was selected by Novell to power their Pulse product 
after they evaluated a number of different technologies. 

Lift's Comet implementation uses a single HTTP connection to poll for changes to an arbitrary 
number of components on the page. Each component has a version number. The long poll in- 
cludes the version number and the component GUID. On the server side, a listener is attached to 
all of the GUIDs listed in the long poll requests. If any of the components has a higher version 
number (or the version number increases during the period of the long poll), the deltas (a set of 
JavaScript describing the change from each version) is sent to the client. The deltas are applied 
and the version number on the client is set to the highest version number for the change set. 

Lift integrates long polling with session management so that if a second request comes into the 
same URL during a long poll, the long poll is terminated to avoid connection starvation (most 
browsers have a maximum of 2 HTTP connections per named server). Lift also supports DNS 
wild-carded servers for long poll requests such that each tab in the browser can do long polling 
against a different DNS wildcarded server. This avoids the connection starvation issues. 

Lift dynamically detects the container the Servlet is running in and on Jetty 6 & 7 and (soon) 
Glassfish, Lift will use the platform's "continuations" implementation to avoid using a thread 
during the long poll. 

Lift's JavaScript can sit on top of jQuery and YUI (and could sit on top of Prototype/Scriptaculous 
as well.) The actual polling code includes back-off on connection failures and other "graceful" 
ways of dealing with transient connection failures. 

I've looked at Atmosphere and CometD (both JVM-oriented Comet technologies). Neither had 
(at the time I evaluated them) support for multiple components per page or connection starvation 
avoidance. 
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Chapter 23 



Advanced Concepts 



23.1 Snippet Resolution 



Lift snippets transform markup to dynamic content. The are functions that transform NodeSeq 
=> NodeSeq. 

Snippets can be invoked from templates via tags: 

i <lift : surround with="def ault " at="content "> 

2 <p> 

3 You have reached this page, but you can only get here if you've logged in 

4 first . 

5 </p> 

6 </lift : surround> 



or via class attributes. 

i <p class=" lift : surround?with=def ault ; at=content "> 

2 You have reached this page, but you can only get here if you've logged in 

3 first . 

4 </p> 



In both cases, the surround (See Section 9.11) snippet will be invoked with attribute with set to 

default and at set to content. Theparameter passed to the surround NodeSeq => NodeSeq 
function is: 

i <p> 

2 You have reached this page, but you can only get here if you've logged in 

3 first . 

4 </p> 



Lift will resolve from the snippet name to a function in the following steps. 
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23.1.1 Lif tSession . lif tTagProcessing 

Lift consults a List [PartialFunction [ (String, Elem, MetaData, NodeSeq, 
String), NodeSeq]] located in Lif tSession.lif tTagProcessing for the rules to use to 
evaluate the snippet name, attributes, etc. into the resulting NodeSeq. LiftSes- 
sion . lif tTagProcessing is the result of Lif tRules . lif tTagProcessing or else 
the default Lift tag processor. If you need special snippet resolution mechanisms, you can 
place them in LiftRules . liftTagProcessing. By default, the snippets get processed by 
Li ft Session .process Snippet . 



23.1.2 LiftRules . liftTagProcessing 

LiftRules . liftTagProcessing looks for the form attribute and sets the isForm variable. 
Next, Lift determines if the contents of the snippet should be evaluated eagerly by looking for one 

of eager_eval, 1 : eager_eval, or lif t : eager_eval attributes. 

If the snippet is an eager evaluation, the child tags will be evaluated for any snippets. 

Either the originally passed children or the eagerly evaluated children will be referred to as chil- 
dren in the next section. 



23.1.3 Snippet name resolution 

Lift looks for the named snippet in the following locations in order: 

• S . locateMappedSnippet - the complete snippet name without any camel or snake ap- 
plication is used to look up a NodeSeq => NodeSeq in within the scope of the current 
extended request 1 . Snippets may be registered using S . mapSnippet. 

• SiteMap Loc snippet - the current SiteMap Loc (S. location) will be queried 
to see if it has a NodeSeq => NodeSeq that matches the current snippet name 

(loc. snippet (snippet Name) ). 

• Li f tRules . snippet s - next, the snippet name is split at the '.' character to determine the 
snippet name and snippet method name. The snippets RulesSeq is tested for a match 
between the List [ String] that results from splitting the name at the period and NodeSeq 
=> NodeSeq. 

• If the above mechanisms do not result in a NodeSeq => NodeSeq, Lift looks f or a C 1 a s s that 
matches the name. 

- S . snippetForClass - is checked to see if a Class has been associated with the snip- 
pet name. If none is found... 



For the purposes of this discussion, the extended request is the scope of a RequestVar. This is the scope of a 
full page render plus any subsequent Ajax operations that originate from that page. This means that a snippet may be 
registered using S .mapSnippet during page rendering and the same snippet function with the same scope binding 
will be used by any Ajax commands. 
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- Lif tRules . snippetDispatch is checked to see if theres an instance of Dispatch- 
Snippet that matches to snippet name. Lift's built-in snippets are registered with 
Lif tRules . snippetDispatch. If there's no match... 

- Lift tries reflection to find a matching class name (note that Lift will try camel 
case and snake case for class names, so the f oo_bar snippet will match the class 
foo_bar as well as FooBar). Lift looks for classes in the snippet subpack- 
age of all the packages added via Lif tRules . addToPackages. So if you call 
Lif tRules . addToPackages ( "f oo .bar" ) in Boot . scala, then Lift will search for 
the classes f oo .bar . snippet . f oo_bar and f oo .bar . snippet . FooBar. 

- Once the class is found, Lift will try to instantiate the class the following ways: 

* Lift will look at the current location (S . location) and if the parameter type of 
the Loc is not Unit, Lift get the current parameter and look for a constructor that 
matches the current parameter type or Box of current parameter type (and super- 
classes of both). If there's a match the constructor will be called with the param- 
eters. For example, if the current page is a Loc [Dog] and Dog is a subclass of 
Animal, the following constructors will match: 

• class MySnippet (dog: Dog) 

• class MySnippet (animal : Animal) 

• class MySnippet (dog: Box [Dog]) 

• class MySnippet (animal : Box [Animal]) 

• class MySnippet (dog : Dog, session: LiftSession) 

• class MySnippet (animal : Animal, session: LiftSession) 

• class MySnippet (dog : Box [Dog], session: LiftSession) 

• class MySnippet (animal : Box [Animal], session: LiftSes- 
sion) 

* If a typed constructor cannot be found, try the zero argument constructor; 

* If the zero argument constructor cannot be found, try to treat the Class as a Scala 
object singleton and get the instance that the singleton refers to. 

- Once we've got an instance of the potential snippet handling class: 

* If it's a Statef ulSnippet, register with S . overrideSnippetForClass; 

* Update the LiftSession snippetMap RequestVar so subsequent references to 
the snippet during the same extended request uses same instance (that way if any 
instance variables are set on the class instance, they are picked up by subsequent 
accesses to the same snippet); 

* Next, Lift attempts to invoke the snippet method. If no explicit method is given, 
the render method is used. 

• Stateful and Dispatch use dispatch method to find the NodeSeq => Node- 
Seq 

• Non-dispatch, do the following method lookup: 

• method that takes no parameters and returns CssBindFunc, NodeSeq => 
NodeSeq, invoke the method and apply the function to the children; or 

■ try to invoke the named method with Group (children) (NodeSeq signa- 
ture) or invoke it with no parameters. If the return value is NodeSeq, Node, or 
Seq [Node ] , then it was successful. 
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23.1.4 Post-processing of results 

• LiftRules.snippetDispatch (built in snippets registered here) 

parallel snippets 

23.2 The Merging Phase 



Part IV 



Misc 
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24.1 Lift 2.2-RC1 

December 8, 2010 

The Lift team is pleased to announce Lift 2.2-RC1. In the month since the 2.2-M1 release, the team 
has closed 53 tickets and made significant improvements to Lift based on community feedback. 

Lift is an elegant, expressive framework that allows any size team build and maintain secure, 
highly interactive, scalable web applications quickly and efficiently. Lift is built on Scala and 
compiles to JVM byte-code. Lift applications deploy as WAR files on popular application servers 
and web containers including Jetty, Glassfish and Tomcat. Lift applications can be monitored 
and managed with the same proven infrastructure used to manage and monitor any Java web 
application. Lift is open source licensed under an Apache 2.0 license. 

Lift features include: 

• Community... the Lift community is 2,400 members strong, super-active and always there to 
help with questions 

• Best Comet (server-push) support that allows the creation of dynamic application such as 
Novell Vibe 

• Super simple Ajax for creating highly interactive web applications without worrying about 
HTTP plumbing 

• Secure by default... Lift apps are resistant to the OWASP top 10 vulnerabilities including 
XSS, XSRF, and parameter tampering 

• Concise and Maintainable... Lift apps typically contain fewer lines of code than correspond- 
ing Rails apps, yet are type safe so that many errors are flagged by the compiler 

• Scalable... Lift apps scale to millions of users across many servers, yet are highly efficient for 
single-box implementations 

• Compatible... Lift apps can take advantage of any Java library as well as the growing collec- 
tion of Scala libraries 



Lift 2.2-RC1 improvements include: 

• HTML5 Support: Lift supports parsing HTML5 input files and rendering HTML5 to the 
browser in addition to Lift's XHTML support 

• Wiring: Spreadsheets meet web application yielding an automatic mechanism for updating 
dependent elements on a page, making it even easier to build dynamic apps with Lift 

• Wizard and Screen Improvements: Build complex screens more easily with new helper 
methods for creating form elements and improved life-cycle callbacks 

• CSS Selector Transforms Improvements: including appending attributes, multiple selectors 
applying to a single element, and element lifting 
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• Support for migratory sessions: ContainerVar s provide type-safe, guaranteed serializable 
session variables that can migrate across application servers in a cluster 

• Improved il8n: including per-page localization strings and localization strings and HTML 
stored in templates rather than Java resource files which makes editing much easier 

• Security Improvements: including creation of new sessions on login 

• MongoDB Improvements: performance improvements as well as new features 

• Support for Scala 2.8.1 as well as 2.8.0 and 2.7.7 

• ProtoUser support for Record: Lift's ProtoUser and CRUDif y canbe used on Record-based 
persistence classes as well as Mapper-based persistence classes 

• Squeryl integration improvements: Lift is updated to use the latest version of Squeryl 

Lift-powered sites include: 

• Foursquare: the multi-million user location based service that services millions of check-ins 
a day on their Lift-powered system 

• Novell Vibe: enterprise collaboration software platform based on Google Wave 

• Innovation Games: The fun way to do serious business - seriously 

• Xerox/XMPie: the leading provider of software for cross-media, variable data one-to-one 
marketing 

• Exchango: The easy and convenient way to give and get free stuff. 

• Snapsort: Compare and decide on cameras 

• No Fouls: Find pickup basketball games 

Please join the Lift community and help use grow Lift. And a super-big thanks to the 30+ Lift 
committers who have grown the Lift community and code-base to what it is today... and what it 
will be in the future! 
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24.2 Lift 2.2 

January 5, 2011 

The Lift team is pleased to announce Lift 2.2. In the three months since the 2.1 release, the team has 
closed over 100 tickets and made significant improvements to Lift based on community feedback. 

Lift is an elegant, expressive framework that allows any size team build and maintain secure, 
highly interactive, scalable web applications quickly and efficiently. Lift is built on Scala and 
compiles to JVM byte-code. Lift applications deploy as WAR files on popular application servers 
and web containers including Jetty, Glassfish and Tomcat. Lift applications can be monitored 
and managed with the same proven infrastructure used to manage and monitor any Java web 
application. Lift is open source licensed under an Apache 2.0 license. 

Lift features include: 

• Community... the Lift community is 2,400 members strong, super-active and always there to 
help with questions 

• Best Comet (server-push) support that allows the creation of dynamic application such as 
Novell Vibe 

• Super simple Ajax for creating highly interactive web applications without worrying about 
HTTP plumbing 

• Secure by default... Lift apps are resistant to the OWASP top 10 vulnerabilities including 
XSS, XSRF, and parameter tampering 

• Concise and Maintainable... Lift apps typically contain fewer lines of code than correspond- 
ing Rails apps, yet are type safe so that many errors are flagged by the compiler 

• Scalable... Lift apps scale to millions of users across many servers, yet are highly efficient for 
single-box implementations 

• Compatible... Lift apps can take advantage of any Java library as well as the growing collec- 
tion of Scala libraries 



Lift 2.2 improvements include: 

• HTML5 Support: Lift supports parsing HTML5 input files and rendering HTML5 to the 
browser in addition to Lift's XHTML support 

• Wiring: Spreadsheets meet web application yielding an automatic mechanism for updating 
dependent elements on a page, making it even easier to build dynamic apps with Lift 

• Wizard and Screen Improvements: Build complex screens more easily with new helper 
methods for creating form elements and improved life-cycle callbacks 

• CSS Selector Transforms Improvements: including appending attributes, multiple selectors 
applying to a single element, and element lifting 
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• Support for migratory sessions: ContainerVar s provide type-safe, guaranteed serializable 
session variables that can migrate across application servers in a cluster 

• Improved il8n: including per-page localization strings and localization strings and HTML 
stored in templates rather than Java resource files which makes editing much easier 

• Security Improvements: including creation of new sessions on login 

• MongoDB Improvements: performance improvements as well as new features 

• Support for Scala 2.8.1 as well as 2.8.0 and 2.7.7 

• ProtoUser support for Record: Lift's ProtoUser and CRUDif y canbe used on Record-based 
persistence classes as well as Mapper-based persistence classes 

• Squeryl integration improvements: Lift is updated to use the latest version of Squeryl 

• Designer-friendly templates 

• Stateless renderingincluding the HTML pipeline 

• Support for MVC-style development 

Lift-powered sites include: 

• Foursquare: the multi-million user location based service that services millions of check-ins 
a day on their Lift-powered system 

• Novell Vibe: enterprise collaboration software platform based on Google Wave 

• Innovation Games: The fun way to do serious business - seriously 

• Xerox/XMPie: the leading provider of software for cross-media, variable data one-to-one 
marketing 

• Exchango: The easy and convenient way to give and get free stuff. 

• Snapsort: Compare and decide on cameras 

• No Fouls: Find pickup basketball games 

Please join the Lift community and help use grow Lift. And a super-big thanks to the 30+ Lift 
committers who have grown the Lift community and code-base to what it is today... and what it 
will be in the future! 
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